Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
167 lines (141 loc) · 4.77 KB

ARCHITECTURE.md

File metadata and controls

167 lines (141 loc) · 4.77 KB

Sejong Pulse System Architecture

This document describes the runtime architecture of Sejong Pulse. It contains two diagrams: a component-level flowchart of the system, and a sequence diagram of the student sign-in and onboarding bootstrap flow. For a project overview and setup instructions, see the root README. For a more detailed deployment topology, see PROJECT_DIAGRAM.md.

The flowchart below reflects the current runtime architecture in this repository.

flowchart LR
  U["Student User"] --> W["Browser / Mobile Web"]

  subgraph Design["Design & Prototype Assets (non-runtime)"]
    Proto["HTML prototype folders
    splash_auth, onboarding,
    global_feed, flash_chats,
    thread_conversation, etc."]
    Glass["aether_glass/DESIGN.md"]
  end

  subgraph FE["Frontend (Next.js App Router)"]
    Pages["Pages
    /login, /onboarding, /pulse,
    /discovery, /advisor,
    /messages/chats, /profile, /settings"]
    Client["Client integration layer
    lib/api.ts, supabase.ts,
    cloudinary.ts, algolia.ts, sendbird.ts"]
    UI["Shared UI
    Navbar, components, hooks"]
  end

  subgraph BE["Backend (FastAPI)"]
    Auth["Auth bootstrap
    /api/auth/sejong/session"]
    Social["Social APIs
    /pulses, /comments,
    /recommendations, /profiles"]
    Utility["Utility APIs
    /upload/sign,
    /chat/create-user,
    /auth/send-welcome,
    /health"]
    AI["AI APIs
    /advisor/query,
    /pulses/translate"]
    Services["Backend service modules
    chat.py, search.py,
    upload.py, email.py"]
    Knowledge["In-memory knowledge index
    knowledge_index.json"]
  end

  subgraph SB["Supabase"]
    SA["Auth"]
    DB["Postgres + RLS
    profiles, pulses, comments"]
  end

  subgraph EXT["External Services"]
    Sejong["Sejong systems
    via sejong-univ-auth"]
    Sendbird["Sendbird"]
    Cloudinary["Cloudinary"]
    Algolia["Algolia"]
    OpenRouter["OpenRouter
    Gemini 2.0 Flash"]
    SendGrid["SendGrid"]
    Sentry["Sentry"]
  end

  subgraph DataPrep["Knowledge ingestion pipeline"]
    Excel["2026 Spring lecture schedule
    Excel source"]
    Extract["extract_knowledge.py"]
    CSV["courses.csv + professors.csv"]
    Ingest["ingest_knowledge.py"]
  end

  Design -. "informs implemented UX" .-> FE

  W --> Pages
  Pages --> Client
  Pages --> UI

  Client -->|"Supabase JS auth/session"| SA
  Client -->|"Direct reads/writes for profiles
  and some client-side queries"| DB

  Client -->|"REST /api/*"| Auth
  Client -->|"REST /api/*"| Social
  Client -->|"REST /api/*"| Utility
  Client -->|"REST /api/*"| AI

  Client -->|"Search-only client"| Algolia
  Client -->|"Direct signed upload"| Cloudinary
  Client -->|"Chat SDK connection"| Sendbird

  Auth -->|"Verify student credentials"| Sejong
  Auth -->|"Admin create/update auth user"| SA
  Auth -->|"Check onboarding profile"| DB

  Social -->|"Service-role reads"| DB
  Social -->|"User-scoped writes via
  Bearer JWT + RLS"| DB
  Social --> Services

  Utility --> Services
  AI --> Knowledge
  AI --> OpenRouter

  Services -->|"Provision/update chat users"| Sendbird
  Services -->|"Generate upload signatures"| Cloudinary
  Services -->|"Index / soft-delete pulses"| Algolia
  Services -->|"Send welcome email"| SendGrid

  Excel --> Extract --> CSV --> Ingest --> Knowledge

  FE -. "browser-side errors" .-> Sentry
  BE -. "backend traces and exceptions" .-> Sentry
Loading

Sejong Login Sequence

This sequence shows the current student sign-in and onboarding bootstrap flow.

sequenceDiagram
  participant User as Student User
  participant FE as Next.js Frontend
  participant API as FastAPI Backend
  participant Sejong as Sejong Systems
  participant SupaAdmin as Supabase Admin Auth
  participant SupaClient as Supabase Client Auth
  participant DB as Supabase Postgres

  User->>FE: Enter student ID and portal password
  FE->>API: POST /api/auth/sejong/session
  API->>Sejong: Verify credentials via sejong-univ-auth

  alt Credentials invalid
    Sejong-->>API: auth failed
    API-->>FE: 401 Invalid Sejong student ID or password
    FE-->>User: Show auth error
  else Credentials verified
    Sejong-->>API: auth success + profile seed
    API->>SupaAdmin: Find or create internal Supabase auth user
    SupaAdmin-->>API: user id + internal email
    API->>DB: Check whether profile exists
    DB-->>API: profile exists or missing
    API-->>FE: email, has_profile, profile_seed
    FE->>SupaClient: signInWithPassword(email, same password)
    SupaClient-->>FE: session + access token

    alt Profile exists
      FE-->>User: Redirect to /pulse
    else Profile missing
      FE-->>User: Redirect to /onboarding
      User->>FE: Submit pseudonym, major, building
      FE->>DB: Insert profile row using Supabase client session
      DB-->>FE: Profile created
      FE-->>User: Redirect to /pulse
    end
  end
Loading