How dharunamikaze/odyssey works
Project Type and Purpose
• Full-stack web application built with Next.js and React.
• Gamified habit‐tracking/personal-growth engine using neuroscience, Stoicism, game mechanics.
• Provides both pre-rendered pages (SSR/SSG) and serverless API endpoints.
High-Level Architecture Components
Main moving parts:
• Client (Browser)
– React components under components/ and src/app/* render UI.
– Context providers (PageContext) manage client state.
– TailwindCSS for styling; static assets from public/.
• Next.js Server (Node.js)
– File-based routing under src/app/ for page rendering (SSR/SSG).
– API routes under src/app/api/* implement serverless functions.
– Middleware (app/middleware.ts & lib/middleware.ts) for auth, routing logic.
– Builds and bundling via Turbopack (config.turbopack.js)
• Data Layer / Backend Services
– Firebase (Firestore + Auth) accessed via lib/firebase.ts (client) and lib/firebaseAdmin.ts (server).
– Data and configuration in data/levels.tsx and src/constants/navItems.tsx.
• External Services
– Firebase Authentication
– Firestore Database
– (Future: AI service, calendar integrations, leaderboard service, etc.)
Relationships and Data Flows
• Page request flow:
1. User opens Browser → HTTP GET to Next.js server.
2. Next.js matches route in src/app/... → executes getServerSideProps or server component.
3. Server-side logic uses firebaseAdmin SDK → reads/writes Firestore.
4. Rendered HTML + JSON sent back → Browser hydrates into React app.
• Client-side interaction flow:
1. In-page React calls Firebase client SDK → direct reads/writes to Firestore.
2. For specialized operations or secure data, client calls Next.js API route → serverless function uses firebaseAdmin.
• Static assets:
– Browser fetches .css, .glb, images from public/ (possibly served by CDN).
Architectural Patterns and Design Principles
• File-based routing (Next.js App Router).
• Hybrid rendering: SSR, SSG, client components & server components.
• Serverless functions for API (Zero server maintenance).
• Separation of concerns:
– components/ui, components/charts for presentational UI
– context for state management
– lib for utilities, middleware, Firebase wrappers
– data/constants for domain data
Technologies and Frameworks
• Next.js (React, App Router)
• TypeScript
• TailwindCSS
• Turbopack / Vercel build pipeline
• Firebase (Auth + Firestore)
• Vercel / Node.js serverless environment (implied)
Final Checklist
• All main components represented
• Data flows and dependencies clearly arrowed
• Annotations for SSR vs. client rendering
• Notes on future extension points (AI service, calendar integration)