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)
                    |
                    | Secure HTTPS API Calls (JWT)
                    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, database tables, CORS policy, and /api/v1 router.
• 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

All protected routes use an Authorization header containing the issued JWT.

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, JWT secret, and email settings. 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 Challenge Arena limits the browser to three arena runs per day and the chat endpoint is limited to ten requests per minute by the backend.
• 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 and login returns a JWT bearer token.
• 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.
• 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.