FlowStudy

FlowStudy is a gamified academic command center for UK university students. It brings assignments, timetable events, AI study guidance, and short knowledge challenges into one focused workspace.

The repository is built on a resilient, decoupled architecture designed for edge deployment. The frontend is hosted on Vercel, securely communicating with a containerized FastAPI backend on Railway, backed by a serverless PostgreSQL database on Neon.

What the app does

• Dashboard: Loads live assignments and timetable events, shows active and completed workload, and presents a daily AI briefing.
• AI Assistant: Uses the user's profile, assignments, and timetable as context. It can return guidance and request Kanban status changes through a structured tool call.
• Assignments Kanban: Displays LMS assignments in To Do, In Progress, and Completed columns. Cards can be dragged between columns.
• Master Timetable: Parses an ICS feed into a weekday calendar with lecture, lab, and seminar styling, week navigation, and a current-time indicator.
• Challenge Arena: Generates five multiple-choice questions for a selected module, topic, difficulty, course, and user level. Correct answers award XP. Rank titles progress through Novice, Scholar, Architect, Grandmaster, and Void Walker.
• Onboarding and Settings: Stores the university, degree/course, Canvas ICS URL, timetable ICS URL, and theme.
• Account Flows: Supports university-email registration with OTP verification, password login, password reset, profile edits, and OTP-protected account deletion.
• Appearance: Includes four persisted themes: Glassmorphism, Arctic Frost, Midnight Blossom, and Cyber Terminal.

Architecture

flowstudy.co.uk (Next.js Edge / Vercel)
                    |
                    | HTTPS + HttpOnly cookie sessions
                    v
api.flowstudy.co.uk (FastAPI / Railway)
          |                 |                 |
     Neon (PostgreSQL)  ICS feeds    Google Gemini

Frontend

• frontend/app/ contains the App Router pages for landing, authentication, onboarding, dashboard, assignments, timetable, challenge, about, and in-app documentation.
• frontend/components/Navbar.tsx provides route navigation, authentication-aware actions, theme selection, and sign out.
• frontend/lib/constants.tsx contains landing-page feature metadata and theme definitions.
• react-markdown with remark-gfm renders the technical guide at /readme.

Backend

• backend/app/main.py creates the FastAPI application, trusted-origin/CORS policy, and /api/v1 router; Alembic owns the database schema.
• backend/app/api/v1/endpoints/ contains authentication, user, dashboard, assignment, and challenge routes.
• backend/app/services/ics_parser.py fetches and normalizes ICS feeds for assignments and timetable events.
• backend/app/services/ai_service.py calls Gemini for daily briefings, chat responses, and arena questions.
• backend/app/models/ and backend/app/schemas/ define persistence models and API contracts.

Main API surface

Protected routes use short-lived HttpOnly access cookies bound to revocable, rotating database sessions. The frontend never reads authentication secrets.

Local development

Prerequisites

• Node.js and npm
• Python 3.12 or newer
• A PostgreSQL database reachable through the backend configuration
• A Gemini API key for AI features
• An email provider configuration for OTP flows

Backend

cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8000

Set the backend environment values before starting it. At minimum, configure the database connection, GEMINI_API_KEY, a 32-byte-or-longer SECRET_KEY, and email settings. Set COOKIE_SECURE=false only for local HTTP development; production defaults to Secure cookies. Do not commit .env files or credentials.

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000. The production commands are npm run build followed by npm run start; npm run lint runs the configured ESLint checks.

Data and caching notes

• Dashboard, assignment, and timetable pages use local storage for a fast cached first render, then request fresh data from the API.
• The dashboard uses session storage to avoid repeatedly requesting the daily AI briefing in the same browser session.
• The backend enforces three Arena attempts per UTC day, validates answers, and awards XP once per completed attempt.
• ICS feeds are fetched on demand and are not a replacement for the university's source system.

Security and production readiness

• Passwords are hashed with bcrypt. Login sets host-only Secure, HttpOnly, SameSite cookies; the 15-minute access token is bound to a revocable database session and the seven-day refresh token rotates on use.
• Cookie-authenticated writes reject untrusted browser origins, and password reset revokes every active session for the account.
• Registration, password reset, profile changes, and account deletion use six-digit email OTPs where applicable.
• User-owned records are filtered by the authenticated user on backend queries.
• The frontend enforces a source-restricted Content Security Policy plus HSTS, clickjacking, MIME-sniffing, referrer, and browser-feature controls. The API applies a JSON-only CSP and prevents authenticated responses from being cached.
• https://flowstudy.co.uk is the canonical origin. The www host redirects permanently to the apex, public pages have route-specific social metadata, and account/private routes are marked noindex.
• In production, secrets are injected via Vercel and Railway environment variables. CORS is strictly restricted to the flowstudy.co.uk origin, and the API is served securely over HTTPS via the api.flowstudy.co.uk subdomain.

Project status

FlowStudy is an actively developed beta. The /about page describes the product vision, while /readme exposes the same technical overview inside the application.