harsha-98h/storyflow

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