Sejong Pulse

A campus-first social platform with a Next.js frontend, a FastAPI backend, Supabase-backed identity and data, AI-assisted advisor flows, and supporting services for messaging, search, recommendations, billing, and media delivery.

Full documentation: sejongpulse-docs.netlify.app

Overview · Features · Architecture · Technology stack · Repository layout · Quick start · Configuration · Deployment · Documentation

---

Demo

The animation above is a silent preview. If it does not play, watch the full recording with audio on YouTube, or download docs/media/demo.mp4.

Overview

Sejong Pulse is a social platform scoped to a single university community. Access is gated by Sejong University credentials, so every participant is a verified member of the campus. Once authenticated, students share short posts ("pulses"), follow campus activity on a live presence map, consult an AI advisor for course and faculty information, and communicate through direct messages, group channels, and calls.

The system is organized as a monorepo: a Next.js application for the client experience, a FastAPI application and background workers for server logic, Supabase for identity and persistence, and a set of integrated services for search, recommendations, messaging, media, and billing.

Features

• Sejong student sign-in. Authentication is performed against Sejong University systems through the sejong-univ-auth library; verified identities are bootstrapped into Supabase Auth. Portal passwords are never stored.
• Pulse feed. Students publish short posts with media, reactions, comments, and on-demand translation, organized into Global, Following, and Academic views.
• Discovery and campus presence. A live map and utility hub surface trending tags, activity analytics, and nearby campus presence.
• AI advisor. A retrieval-assisted assistant answers questions about courses and professors, backed by a structured academic knowledge index and an OpenRouter-hosted Gemini model.
• Messaging and channels. Direct chats, broadcast channels, and calls are delivered through Sendbird, with live audio and video provided by LiveKit.
• Recommendations. Feed ranking and discovery suggestions are computed with Gorse and delivered through a dedicated recommendation worker.
• Billing. Subscription and pass purchases are processed through the billing service.
• eCampus browser agent. A Stagehand-based runtime can navigate Sejong eCampus under supervised, observation-oriented controls. See AGENT.md.

Architecture

The diagram below summarizes the runtime architecture. The complete set of diagrams, including the sign-in sequence, is maintained in ARCHITECTURE.md, and a more detailed deployment topology is available in PROJECT_DIAGRAM.md.

flowchart LR
  U["Student user"] --> W["Browser / mobile web"]

  subgraph FE["Frontend (Next.js App Router)"]
    Pages["Pages: login, onboarding, pulse,
    discovery, advisor, messages, profile, settings"]
    Client["Client integration layer
    api.ts, supabase.ts, sendbird.ts,
    cloudinary.ts, algolia.ts, tossPayments.ts"]
  end

  subgraph BE["Backend (FastAPI + workers)"]
    API["API surface
    auth, pulses, comments, recommendations,
    channels, moderation, notifications, billing"]
    Services["Service layer
    chat, search, upload, livekit,
    recommendation, billing, job queue"]
    Workers["Background workers
    job worker, recommendation worker, cron"]
  end

  subgraph SB["Supabase"]
    SA["Auth"]
    DB["Postgres + RLS"]
  end

  subgraph EXT["External services"]
    Sejong["Sejong systems (sejong-univ-auth)"]
    Sendbird["Sendbird"]
    LiveKit["LiveKit"]
    Cloudinary["Cloudinary"]
    Algolia["Algolia"]
    Gorse["Gorse"]
    Toss["Toss Payments"]
    OpenRouter["OpenRouter (Gemini)"]
  end

  W --> Pages --> Client
  Client -->|Supabase auth/session| SA
  Client -->|REST /api/*| API
  Client --> Sendbird
  Client --> Cloudinary
  Client --> Algolia

  API --> Services
  API --> SA
  API --> DB
  Services --> Sejong
  Services --> OpenRouter
  Services --> Sendbird
  Services --> LiveKit
  Services --> Gorse
  Services --> Toss
  Workers --> DB
  Workers --> Gorse

Loading

Technology stack

Layer	Technology
Frontend	Next.js 16 (App Router), React 19, TypeScript
Backend	FastAPI, Python 3.13, Uvicorn
Identity and data	Supabase Auth, Supabase Postgres with row-level security
Caching and queues	Redis
Messaging and calls	Sendbird, LiveKit
Search	Algolia
Recommendations	Gorse
Media	Cloudinary
AI	OpenRouter (Gemini), local academic knowledge index
Billing	Toss Payments
Email	SendGrid
Monitoring	Sentry
Browser automation	Stagehand (Node.js runtime)
Hosting	Render (backend and workers), Netlify (frontend)

Repository layout

.
├── frontend/                 Next.js application (App Router, client integration layer)
├── backend/                  FastAPI application, services, and background workers
│   └── agent_runtime/        Stagehand (Node.js) browser-agent runtime
├── tools/
│   └── campus-auth-java/     Vendored standalone Sejong credential verifier (test/backup)
├── gorse/                    Recommendation engine configuration
├── aether_glass/             Design direction and concept references
├── docs/media/               README assets (demo recording)
├── ARCHITECTURE.md           Architecture and sign-in sequence diagrams
├── PROJECT_DIAGRAM.md        Detailed deployment topology diagram
├── AGENT.md                  eCampus browser-agent module guide
├── render.yaml               Render service definitions (web, workers, cron)
└── docker-compose.*.yml      Local Gorse and LiveKit support

The repository also contains static HTML prototype folders (for example global_feed, dashboard_map, and onboarding) that document the original interaction design and are not part of the runtime.

Quick start

The steps below provide a minimal local bring-up. For the complete prerequisites, optional local infrastructure, and database setup, follow the Getting Started guide in the documentation site.

Backend (FastAPI):

cd backend
pip install -r requirements.txt
cp .env.example .env        # populate required values
python -m uvicorn main:app --host 0.0.0.0 --port 8000

Frontend (Next.js):

cd frontend
npm install
cp .env.local .env.local    # populate NEXT_PUBLIC_* values
npm run dev

The application is then available at http://localhost:3000, and the API at http://localhost:8000 with a health check at /api/health.

Background workers and the eCampus agent runtime are optional for local development. The worker entry points are defined in render.yaml (scripts/start_job_worker.sh, scripts/start_recommendation_worker.sh), and the agent runtime is documented in AGENT.md.

Configuration

Configuration is provided through environment variables. Use the example files as a reference and consult the Configuration Guide for the full list.

• Backend — backend/.env.example. Key groups include Supabase (SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY), AI gateway (OPENAI_API_KEY, OPENAI_API_BASE_URL, AI_CHAT_MODEL_*), messaging and media (SENDBIRD_*, LIVEKIT_*, CLOUDINARY_*, ALGOLIA_*), recommendations (GORSE_*), billing (TOSS_PAYMENTS_*), Redis (REDIS_URL), and Sejong sign-in (SEJONG_AUTH_INTERNAL_EMAIL_DOMAIN).
• Agent runtime — backend/agent_runtime/.env.example.
• Frontend — NEXT_PUBLIC_* variables, including NEXT_PUBLIC_API_BASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_SENDBIRD_APP_ID, NEXT_PUBLIC_ALGOLIA_*, and NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME.

Secrets must never be committed. Portal passwords and API keys are kept server-side and are not written to logs.

Deployment

• Backend and workers are deployed on Render using render.yaml, which defines the web service (sejongpulse-backend), a job worker, a recommendation worker, and a daily recommendation backfill cron. The web service exposes a health check at /api/health.
• Frontend is deployed on Netlify from the frontend directory.

Refer to the documentation site's Technical Overview for the full deployment topology.

Documentation

The complete project documentation is published at sejongpulse-docs.netlify.app and includes:

• About the Project
• Getting Started
• How to Use
• Technical Overview
• API Reference
• Configuration Guide
• Maintenance and Troubleshooting
• Contribution Guidelines
• FAQ and Release Notes

In-repository documents:

Document	Description
ARCHITECTURE.md	System architecture and sign-in sequence diagrams
API.md	HTTP API reference for the backend
DEPLOYMENT.md	Deployment topology and operational procedures
CONTRIBUTING.md	Contribution workflow and standards
SECURITY.md	Security policy and vulnerability reporting
ROADMAP.md	Planned direction and priorities
CHANGELOG.md	Notable changes by release
AGENT.md	eCampus browser-agent module guide

Tools

tools/campus-auth-java/ contains a vendored, standalone Java utility that verifies Sejong student credentials independently of the live Python sign-in path. It is intended for testing and as a backup verifier and is not wired into the running application. See tools/campus-auth-java/VENDORED.md.

Contributing

Contributions are welcome. Please review CONTRIBUTING.md and the Contribution Guidelines in the documentation site, keep changes focused, and ensure backend tests pass (pytest in backend/) before opening a pull request. Security issues should be reported privately as described in SECURITY.md.

License

This project is licensed under the Apache License 2.0. See LICENSE for the full text. The vendored utility in tools/campus-auth-java/ retains its own upstream license.