# Technical Overview

Sejong Pulse is organized as a web-first product with a Next.js application on the frontend, a FastAPI service layer on the backend, Supabase for identity and relational storage, and several optional integrations for search, messaging, media, recommendations, and AI.

## Architecture

```{mermaid}
flowchart LR
  user["Student user"] --> fe["Next.js frontend"]

  fe --> api["FastAPI API"]
  fe --> supa["Supabase Auth and Postgres"]
  fe --> sendbird["Sendbird chat SDK"]
  fe --> cloudinary["Cloudinary uploads"]
  fe --> algolia["Algolia search"]

  api --> supa
  api --> redis["Redis cache and queue"]
  api --> gorse["Gorse recommendations"]
  api --> livekit["LiveKit sessions"]
  api --> openrouter["OpenRouter-compatible AI endpoint"]
  api --> sendgrid["SendGrid email"]
  api --> toss["Billing provider"]

  worker["Background worker"] --> redis
  worker --> supa

  reco["Recommendation worker"] --> gorse
  reco --> supa

  knowledge["Knowledge pipeline"] --> index["Knowledge index"]
  api --> index
```

## Frontend

The frontend lives in `stitch/frontend` and uses:

- `Next.js` App Router
- `React 19`
- `TypeScript`
- shared UI components in `src/components`
- API and SDK helpers in `src/lib`

Important route groups:

- Auth flows under `src/app/(auth)`
- Main product surfaces under `src/app/(app)`
- shared application shell in `stitch/frontend/src/components/AppShell.tsx`

## Backend

The backend lives in `stitch/backend` and centers on:

- `main.py` for the primary FastAPI application and the majority of HTTP routes
- `controllers/` for billing and chat-focused routers
- `services/` for external integrations and reusable domain logic
- `worker.py` for asynchronous job handling
- `recommendation_worker.py` for recommendation outbox processing

The service layer includes modules for:

- search and indexing
- billing and plan control
- chat and advisor behavior
- recommendation ranking and outbox delivery
- official channel syncing
- upload signing and media support
- observability and abuse protection

## Data and State

Core platform state is handled through:

- `Supabase Auth` for user identity and sessions
- `Supabase Postgres` for profiles, pulses, comments, notifications, matches, channels, billing records, and feedback
- `Redis` for caching and durable job processing
- `Gorse` for recommendation scoring and synchronization
- a local knowledge index for academic lookup

## Deployment Topology

Current deployment artifacts in the repository point to:

- `Netlify` for the frontend via `stitch/frontend/netlify.toml`
- `Render` for the backend API, workers, and cron jobs via `stitch/render.yaml`
- `Docker Compose` for local LiveKit and Gorse infrastructure

## Non-Runtime Assets

The `stitch/` directory also includes stitched prototypes and diagram documents such as:

- `stitch/read.md`
- `stitch/PROJECT_DIAGRAM.md`

These are valuable references for product documentation even though they are not shipped as part of the runtime application.