# harsha-98h/storyflow architecture

> Architecture diagram of the GitHub repository harsha-98h/storyflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsha-98h/storyflow
- Repository: https://github.com/harsha-98h/storyflow

## Overview

#### Purpose and Active Entry Points
StoryFlow is an English-learning platform delivering daily, upward-scrolling reading lessons, tracking completion/streaks, showing analytics, and storing reminder preferences. The active system is a Next.js frontend plus TypeScript Express/MongoDB API; the Python FastAPI tree is legacy and safety-locked.
- Frontend application root: `frontend/app/layout.tsx`, `frontend/app/page.tsx`
- API process and route composition: `backend/src/server.ts`, `backend/src/app.ts`
- Legacy reference only: `backend/app/main.py`

#### Client Application and Navigation
Next.js App Router supplies public authentication, learning, dashboard, legal, and debug/operations views. Shared providers establish authentication and theme state; browser API access is centralized rather than embedded in individual pages.
- Main user surfaces: `frontend/app/learn/page.tsx`, `frontend/app/dashboard/page.tsx`, `frontend/app/auth/page.tsx`
- Shared session/UI boundaries: `frontend/components/auth-provider.tsx`, `frontend/lib/api.ts`
- Request-level frontend middleware: `frontend/middleware.ts`

#### Authentication and Security Boundary
The Express auth routes implement email/password registration, JWT access/refresh lifecycle, current-user lookup, verification, and password reset. Security controls include password hashing, CSRF double-submit tokens, request validation, rate limiting, CORS/cookie settings, and optional transactional-email providers.
- Auth API and token utilities: `backend/src/routes/auth.ts`, `backend/src/utils/auth.ts`
- Environment/database initialization: `backend/src/config/env.ts`, `backend/src/config/database.ts`
- Global API protection: `backend/src/middleware/rateLimit.ts`, `backend/src/app.ts`

#### Learning Content Delivery
Learning content is modeled and persisted in MongoDB, then selected by the content endpoint for daily lessons. A seed pipeline imports the frontend-owned JSON corpus into the `learningContents` collection; content structures are shared conceptually across the web app and backend.
- Content API/model: `backend/src/routes/content.ts`, `backend/src/models/LearningContent.ts`
- Canonical seed corpus and importer: `frontend/data/learning_content.json`, `backend/src/scripts/seedContent.ts`
- Reader UI: `frontend/components/credits-reader.tsx`, `frontend/app/learn/page.tsx`

#### Progress, Streaks, and Analytics Flow
After a reader marks material read, the API updates per-user progress and streak state. Summary/activity endpoints feed dashboard statistics, while analytics aggregates daily, weekly, monthly, and total reading views.
- Write/read progress flow: `backend/src/routes/progress.ts`, `backend/src/models/UserProgress.ts`, `backend/src/models/Streak.ts`
- Aggregated reporting: `backend/src/routes/analytics.ts`
- Dashboard presentation: `frontend/app/dashboard/page.tsx`, `frontend/components/analytics-charts.tsx`

#### Reminders and Notification Integration
Authenticated clients register Firebase push tokens and email reminder preferences through the reminders API. The frontend includes PWA/service-worker assets and Firebase initialization, while delivery remains optional infrastructure.
- Reminder persistence/API: `backend/src/routes/reminders.ts`, `backend/src/models/UserReminder.ts`
- Firebase/PWA client boundary: `frontend/lib/firebase.ts`, `frontend/public/firebase-messaging-sw.js`, `frontend/public/sw.js`
- Settings UI: `frontend/components/reminder-settings.tsx`

#### Runtime and Deployment Topology
The frontend is intended for Vercel; Express runs as a Node service, intended for Render, connected to MongoDB Atlas. CORS and cookie security bridge the separate browser/frontend/API origins. Optional external services are Firebase Cloud Messaging, Brevo or Resend email, and configured OpenAI moderation/fallback models.
- Backend deployment definition: `backend/render.yaml`
- Node dependencies/process definitions: `backend/package.json`, `frontend/package.json`
- Security CI gate: `.github/workflows/security-smoke.yml`

Main entry points: [`backend/src/app.ts`](https://github.com/harsha-98h/storyflow/blob/main/backend/src/app.ts) (API composition and protection), [`frontend/app/page.tsx`](https://github.com/harsha-98h/storyflow/blob/main/frontend/app/page.tsx) (App Router surfaces), [`backend/src/config/database.ts`](https://github.com/harsha-98h/storyflow/blob/main/backend/src/config/database.ts) (MongoDB Atlas), [`frontend/lib/api.ts`](https://github.com/harsha-98h/storyflow/blob/main/frontend/lib/api.ts) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_next_app["App Router surfaces<br/>Next.js UI<br/>[page.tsx]"]
  node_frontend_middleware["Request middleware<br/>Next.js middleware<br/>[middleware.ts]"]
  node_auth_provider["Session and theme provider<br/>React provider<br/>[auth-provider.tsx]"]
  node_api_client["Browser API client<br/>API boundary<br/>[api.ts]"]
  node_reader["Lesson reader<br/>React component<br/>[credits-reader.tsx]"]
  node_dashboard["Dashboard and charts<br/>React views<br/>[page.tsx]"]
  node_reminder_settings["Reminder settings<br/>React component"]
  node_firebase_client["Firebase and PWA client<br/>push client<br/>[firebase.ts]"]
end

subgraph group_backend["Express API"]
  node_express_server["Node API process<br/>Express server<br/>[server.ts]"]
  node_api_app["API composition and protection<br/>Express app<br/>[app.ts]"]
  node_auth_api["Authentication API<br/>Express routes<br/>[auth.ts]"]
  node_content_api["Daily content API<br/>Express routes<br/>[content.ts]"]
  node_progress_api["Progress and streak API<br/>Express routes<br/>[progress.ts]"]
  node_analytics_api["Analytics API<br/>Express routes<br/>[analytics.ts]"]
  node_reminders_api["Reminders API<br/>Express routes<br/>[reminders.ts]"]
  node_legacy_fastapi["Legacy FastAPI<br/>reference only<br/>[main.py]"]
end

subgraph group_data["Content and data"]
  node_mongo[("MongoDB Atlas<br/>database<br/>[database.ts]")]
  node_content_corpus["Learning content corpus<br/>JSON corpus"]
  node_content_seed["Content seed importer<br/>seed pipeline<br/>[seedContent.ts]"]
end

subgraph group_external["Deployment and integrations"]
  node_vercel["Vercel<br/>frontend hosting<br/>[package.json]"]
  node_render["Render<br/>Node hosting<br/>[render.yaml]"]
  node_notification_services["Push and email providers<br/>optional integration"]
end

node_vercel -->|"hosts"| node_next_app
node_frontend_middleware -->|"guards requests"| node_next_app
node_next_app -->|"uses"| node_auth_provider
node_next_app -->|"learn view"| node_reader
node_next_app -->|"dashboard view"| node_dashboard
node_next_app -->|"settings view"| node_reminder_settings
node_auth_provider -->|"session requests"| node_api_client
node_reader -->|"content and completion"| node_api_client
node_dashboard -->|"statistics"| node_api_client
node_reminder_settings -->|"preferences and tokens"| node_api_client
node_firebase_client -->|"registers push"| node_notification_services
node_reminder_settings -->|"configures push"| node_firebase_client
node_api_client -->|"cross-origin API calls"| node_express_server
node_render -->|"hosts"| node_express_server
node_express_server -->|"serves"| node_api_app
node_api_app -->|"routes"| node_auth_api
node_api_app -->|"routes"| node_content_api
node_api_app -->|"routes"| node_progress_api
node_api_app -->|"routes"| node_analytics_api
node_api_app -->|"routes"| node_reminders_api
node_auth_api -->|"users and tokens"| node_mongo
node_content_api -->|"daily lessons"| node_mongo
node_progress_api -->|"progress and streaks"| node_mongo
node_analytics_api -->|"aggregates activity"| node_mongo
node_reminders_api -->|"preferences"| node_mongo
node_reminders_api -.->|"optional delivery"| node_notification_services
node_content_corpus -->|"source lessons"| node_content_seed
node_content_seed -->|"imports learningContents"| node_mongo

click node_next_app "https://github.com/harsha-98h/storyflow/blob/main/frontend/app/page.tsx"
click node_frontend_middleware "https://github.com/harsha-98h/storyflow/blob/main/frontend/middleware.ts"
click node_auth_provider "https://github.com/harsha-98h/storyflow/blob/main/frontend/components/auth-provider.tsx"
click node_api_client "https://github.com/harsha-98h/storyflow/blob/main/frontend/lib/api.ts"
click node_reader "https://github.com/harsha-98h/storyflow/blob/main/frontend/components/credits-reader.tsx"
click node_dashboard "https://github.com/harsha-98h/storyflow/blob/main/frontend/app/dashboard/page.tsx"
click node_reminder_settings "https://github.com/harsha-98h/storyflow/blob/main/frontend/components/reminder-settings.tsx"
click node_firebase_client "https://github.com/harsha-98h/storyflow/blob/main/frontend/lib/firebase.ts"
click node_express_server "https://github.com/harsha-98h/storyflow/blob/main/backend/src/server.ts"
click node_api_app "https://github.com/harsha-98h/storyflow/blob/main/backend/src/app.ts"
click node_auth_api "https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/auth.ts"
click node_content_api "https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/content.ts"
click node_progress_api "https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/progress.ts"
click node_analytics_api "https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/analytics.ts"
click node_reminders_api "https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/reminders.ts"
click node_mongo "https://github.com/harsha-98h/storyflow/blob/main/backend/src/config/database.ts"
click node_content_corpus "https://github.com/harsha-98h/storyflow/blob/main/frontend/data/learning_content.json"
click node_content_seed "https://github.com/harsha-98h/storyflow/blob/main/backend/src/scripts/seedContent.ts"
click node_vercel "https://github.com/harsha-98h/storyflow/blob/main/frontend/package.json"
click node_render "https://github.com/harsha-98h/storyflow/blob/main/backend/render.yaml"
click node_notification_services "https://github.com/harsha-98h/storyflow/blob/main/frontend/public/firebase-messaging-sw.js"
click node_legacy_fastapi "https://github.com/harsha-98h/storyflow/blob/main/backend/app/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_next_app,node_frontend_middleware,node_auth_provider,node_api_client,node_reader,node_dashboard,node_reminder_settings,node_firebase_client toneBlue
class node_express_server,node_api_app,node_auth_api,node_content_api,node_progress_api,node_analytics_api,node_reminders_api,node_legacy_fastapi toneAmber
class node_mongo,node_content_corpus,node_content_seed toneMint
class node_vercel,node_render,node_notification_services toneRose
```

## Components

### Next.js frontend

- [App Router surfaces](https://github.com/harsha-98h/storyflow/blob/main/frontend/app/page.tsx): Next.js UI · Learning, dashboard, authentication, legal, and operations views. · `frontend/app/page.tsx`
- [Request middleware](https://github.com/harsha-98h/storyflow/blob/main/frontend/middleware.ts): Next.js middleware · `frontend/middleware.ts`
- [Session and theme provider](https://github.com/harsha-98h/storyflow/blob/main/frontend/components/auth-provider.tsx): React provider · `frontend/components/auth-provider.tsx`
- [Browser API client](https://github.com/harsha-98h/storyflow/blob/main/frontend/lib/api.ts): API boundary · Centralizes browser access to the Express API. · `frontend/lib/api.ts`
- [Lesson reader](https://github.com/harsha-98h/storyflow/blob/main/frontend/components/credits-reader.tsx): React component · Renders upward-scrolling reading lessons. · `frontend/components/credits-reader.tsx`
- [Dashboard and charts](https://github.com/harsha-98h/storyflow/blob/main/frontend/app/dashboard/page.tsx): React views · `frontend/app/dashboard/page.tsx`
- [Reminder settings](https://github.com/harsha-98h/storyflow/blob/main/frontend/components/reminder-settings.tsx): React component · `frontend/components/reminder-settings.tsx`
- [Firebase and PWA client](https://github.com/harsha-98h/storyflow/blob/main/frontend/lib/firebase.ts): push client · Firebase initialization plus service-worker assets. · `frontend/lib/firebase.ts`

### Express API

- [Node API process](https://github.com/harsha-98h/storyflow/blob/main/backend/src/server.ts): Express server · `backend/src/server.ts`
- [API composition and protection](https://github.com/harsha-98h/storyflow/blob/main/backend/src/app.ts): Express app · Composes routes with CORS, cookies, CSRF, validation, and rate limiting. · `backend/src/app.ts`
- [Authentication API](https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/auth.ts): Express routes · Registration, JWT lifecycle, verification, reset, and current-user lookup. · `backend/src/routes/auth.ts`
- [Daily content API](https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/content.ts): Express routes · `backend/src/routes/content.ts`
- [Progress and streak API](https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/progress.ts): Express routes · `backend/src/routes/progress.ts`
- [Analytics API](https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/analytics.ts): Express routes · Aggregates daily, weekly, monthly, and total reading activity. · `backend/src/routes/analytics.ts`
- [Reminders API](https://github.com/harsha-98h/storyflow/blob/main/backend/src/routes/reminders.ts): Express routes · `backend/src/routes/reminders.ts`
- [Legacy FastAPI](https://github.com/harsha-98h/storyflow/blob/main/backend/app/main.py): reference only · Safety-locked and not part of the active runtime. · `backend/app/main.py`

### Content and data

- [MongoDB Atlas](https://github.com/harsha-98h/storyflow/blob/main/backend/src/config/database.ts): database · Stores users, content, progress, streaks, and reminders. · `backend/src/config/database.ts`
- [Learning content corpus](https://github.com/harsha-98h/storyflow/blob/main/frontend/data/learning_content.json): JSON corpus · Canonical frontend-owned lesson source. · `frontend/data/learning_content.json`
- [Content seed importer](https://github.com/harsha-98h/storyflow/blob/main/backend/src/scripts/seedContent.ts): seed pipeline · Imports the corpus into learningContents. · `backend/src/scripts/seedContent.ts`

### Deployment and integrations

- [Vercel](https://github.com/harsha-98h/storyflow/blob/main/frontend/package.json): frontend hosting · `frontend/package.json`
- [Render](https://github.com/harsha-98h/storyflow/blob/main/backend/render.yaml): Node hosting · `backend/render.yaml`
- [Push and email providers](https://github.com/harsha-98h/storyflow/blob/main/frontend/public/firebase-messaging-sw.js): optional integration · Firebase Cloud Messaging and Brevo or Resend delivery. · `frontend/public/firebase-messaging-sw.js`

## Connections

- Vercel → App Router surfaces: hosts
- Request middleware → App Router surfaces: guards requests
- App Router surfaces → Session and theme provider: uses
- App Router surfaces → Lesson reader: learn view
- App Router surfaces → Dashboard and charts: dashboard view
- App Router surfaces → Reminder settings: settings view
- Session and theme provider → Browser API client: session requests
- Lesson reader → Browser API client: content and completion
- Dashboard and charts → Browser API client: statistics
- Reminder settings → Browser API client: preferences and tokens
- Firebase and PWA client → Push and email providers: registers push
- Reminder settings → Firebase and PWA client: configures push
- Browser API client → Node API process: cross-origin API calls · CORS and cookie security bridge frontend and API origins.
- Render → Node API process: hosts
- Node API process → API composition and protection: serves
- API composition and protection → Authentication API: routes
- API composition and protection → Daily content API: routes
- API composition and protection → Progress and streak API: routes
- API composition and protection → Analytics API: routes
- API composition and protection → Reminders API: routes
- Authentication API → MongoDB Atlas: users and tokens
- Daily content API → MongoDB Atlas: daily lessons
- Progress and streak API → MongoDB Atlas: progress and streaks
- Analytics API → MongoDB Atlas: aggregates activity
- Reminders API → MongoDB Atlas: preferences
- Reminders API → Push and email providers: optional delivery
- Learning content corpus → Content seed importer: source lessons
- Content seed importer → MongoDB Atlas: imports learningContents