# dharunamikaze/odyssey architecture

> Architecture diagram of the GitHub repository dharunamikaze/odyssey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dharunamikaze/odyssey
- Repository: https://github.com/dharunamikaze/odyssey

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        BROWSER["Browser (UI)"]:::client
        UI["UI Components"]:::frontend
        CTX["PageContext"]:::frontend
        STATIC["Static Assets (public/)"]:::frontend
        BROWSER -->|hydrates| UI
        UI -->|uses| CTX
        BROWSER -->|fetches| STATIC
        click UI "https://github.com/dharunamikaze/odyssey/tree/master/components/"
        click CTX "https://github.com/dharunamikaze/odyssey/blob/master/context/PageContext.tsx"
        click STATIC "https://github.com/dharunamikaze/odyssey/tree/master/public/"
    end

    %% Next.js Server Layer
    subgraph "Next.js Server"
        SSR["App Router Pages (src/app/)"]:::server
        MW_APP["Middleware (app/middleware.ts)"]:::server
        API["API Routes (src/app/api/)"]:::server
        SSR -->|handles routes| MW_APP
        MW_APP -->|guards| SSR
        SSR -->|renders| BROWSER
        SSR -->|calls| API
        click SSR "https://github.com/dharunamikaze/odyssey/tree/master/src/app/"
        click MW_APP "https://github.com/dharunamikaze/odyssey/blob/master/src/app/middleware.ts"
        click API "https://github.com/dharunamikaze/odyssey/tree/master/src/app/api/"
    end

    %% Data Layer
    subgraph "Data & Utils Layer"
        LIB_FIRE["Firebase Client SDK Wrapper"]:::data
        LIB_ADMIN["Firebase Admin SDK Wrapper"]:::data
        UTIL["Utility Functions"]:::data
        DATA_DEF["Data Definitions (data/levels.tsx)"]:::data
        CONST["Nav Constants (src/constants/navItems.tsx)"]:::data
        UI -->|client SDK| LIB_FIRE
        API -->|server SDK| LIB_ADMIN
        SSR -->|server SDK| LIB_ADMIN
        LIB_FIRE -->|reads/writes| DATA_DEF
        UTIL -->|supports| LIB_FIRE
        UTIL -->|supports| LIB_ADMIN
        click LIB_FIRE "https://github.com/dharunamikaze/odyssey/blob/master/lib/firebase.ts"
        click LIB_ADMIN "https://github.com/dharunamikaze/odyssey/blob/master/lib/firebaseAdmin.ts"
        click UTIL "https://github.com/dharunamikaze/odyssey/blob/master/lib/utils.ts"
        click DATA_DEF "https://github.com/dharunamikaze/odyssey/blob/master/data/levels.tsx"
        click CONST "https://github.com/dharunamikaze/odyssey/blob/master/src/constants/navItems.tsx"
    end

    %% External Services
    subgraph "External Services"
        AUTH["Firebase Auth"]:::external
        FIRESTORE["Firestore DB"]:::external
        CDN["CDN (for public/)"]:::external
        LIB_FIRE -->|auth| AUTH
        LIB_FIRE -->|reads/writes| FIRESTORE
        LIB_ADMIN -->|reads/writes| FIRESTORE
        BROWSER -->|fetches| CDN
    end

    %% Config & Build
    subgraph "Config & Build"
        TPACK["Turbopack Config"]:::config
        NEXTCFG["Next.js Config"]:::config
        TAILWINDCFG["TailwindCSS Config"]:::config
        STYLES["Global Styles"]:::config
        click TAILWINDCFG "https://github.com/dharunamikaze/odyssey/blob/master/tailwind.config.ts"
        click STYLES "https://github.com/dharunamikaze/odyssey/blob/master/src/app/globals.css"
        click TPACK "https://github.com/dharunamikaze/odyssey/blob/master/config.turbopack.js"
        click NEXTCFG "https://github.com/dharunamikaze/odyssey/blob/master/next.config.js"
    end

    classDef frontend fill:#D6E8FF,stroke:#00449E;
    classDef client fill:#B3E5FC,stroke:#0277BD;
    classDef server fill:#C8E6C9,stroke:#2E7D32;
    classDef data fill:#FFE0B2,stroke:#EF6C00;
    classDef external fill:#E1BEE7,stroke:#6A1B9A;
    classDef config fill:#ECEFF1,stroke:#607D8B;
```
