# dodao123/cout-love architecture

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

- Interactive diagram: https://gitdiagram.com/dodao123/cout-love
- Repository: https://github.com/dodao123/cout-love

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application (React-based front end + serverless back-end APIs) for managing and viewing albums, audio clips, user notes, and basic analytics, with an admin interface.
- Key features (from file tree & README):
- Server-side rendered pages & client components under src/app
- API routes under src/app/api for albums, notes, uploads, admin auth, analytics, categories
- MongoDB for persistence (scripts/init-db.js, src/lib/mongodb.ts)
- Local file storage for uploads (public/uploads & storage/uploads)
- Tailwind CSS for styling

##### File Structure & Architectural Choices
- Top-level front end: src/app – Next.js App Router directories for pages and UI components
- Top-level back end: src/app/api – Serverless functions (Route Handlers)
- Configuration: next.config.ts, postcss.config.mjs, tailwind.config.js, eslint.config.mjs
- Database abstraction: src/lib/mongodb.ts, src/lib/database.ts, plus init/seed/test scripts in scripts/
- File upload handling: src/app/api/upload, lib/upload.ts, public/uploads & storage/uploads
- Caching/utilities: src/lib/clientCache.ts, lib/albumCache.ts, lib/cacheDebug.ts, lib/fetchWithCache.ts

##### Main Components & Their Roles
A. Client (Browser)
- Renders pages (React Server & Client Components)
- Invokes RESTful APIs for data (fetch/populate albums, notes, categories, analytics)
- Upload interface for audio & avatars
B. Next.js Server
- Serves SSR/SSG pages & static assets (public/)
- Hosts serverless API routes (src/app/api/…)
- Middleware (middleware.ts) for cross-cutting concerns (auth/session)
C. Database (MongoDB)
- Stores albums metadata, notes, user/admin credentials, analytics events, categories
- Initial setup & seeding via scripts
D. File Storage
- Local disk (public/uploads & storage/uploads) for audio, album text, avatars
- Served as static assets by Next.js
E. External/Platform Services
- Vercel (or similar) for deployment (serverless runtime)
- CDN (Next.js automatic) for static asset delivery

##### Relationships & Data Flow
1. User requests page → Next.js App Router → Server Component renders with data.
2. Client-side fetch → API route handler → lib/database or lib/mongodb → MongoDB
3. Upload flow: Client → upload API → lib/upload saves file to storage/uploads → metadata saved in MongoDB → file served from public/uploads on next deploy or via proxy route.
4. Admin login: Client → /api/admin/login → verify credentials in MongoDB → set cookie/session → protected API calls (/api/admin/albums, /api/admin/logout, /api/admin/verify).
5. Analytics: Client events → /api/analytics → store in MongoDB

##### Architectural Patterns & Principles
- Full-stack React with Next.js App Router (Server & Client components)
- Serverless functions (one Route Handler per endpoint)
- Single codebase for front end + back end
- Separation of concerns: UI (app/) vs. API (app/api/) vs. data layer (lib/)
- Modular utilities (caching, fetch wrappers)
- Static asset management & incremental regeneration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Browser["Browser"]:::frontend
    Vercel["Vercel/CDN"]:::external

    %% Next.js Server
    subgraph "Next.js Server" 
        direction TB
        Middleware["middleware.ts"]:::backend
        subgraph "App Router (UI Components)" 
            direction TB
            AppDir["src/app/"]:::frontend
            Layout["layout.tsx"]:::frontend
            Globals["globals.css"]:::frontend
            Home["page.tsx (Home)"]:::frontend
            Gallery["gallery/page.tsx"]:::frontend
            Category["category.tsx"]:::frontend
            PrevSlug["prevSlug/[slug]/page.tsx"]:::frontend
            subgraph "Album Pages"
                direction TB
                AlbumPage["[slug]/page.tsx"]:::frontend
                NotePage["[slug]/Note/page.tsx"]:::frontend
            end
            subgraph "Admin Pages"
                direction TB
                AdminDir["src/app/admin/"]:::frontend
                AdminLogin["Login/page.tsx"]:::frontend
                AdminAdd["addAlbum/page.tsx"]:::frontend
                AdminManage["managerAlbum/page.tsx"]:::frontend
            end
        end
        subgraph "API Route Handlers" 
            direction TB
            ApiDir["src/app/api/"]:::backend
            subgraph "Public APIs"
                direction TB
                AlbumsApi["api/albums/"]:::backend
                SingleAlbumApi["[slug]/route.ts"]:::backend
                NotesApi["notes/route.ts"]:::backend
                UploadApi["upload/route.ts"]:::backend
                AnalyticsApi["analytics/route.ts"]:::backend
                CategoriesApi["categories/route.ts"]:::backend
                HealthApi["health/route.ts"]:::backend
            end
            subgraph "Admin APIs"
                direction TB
                AdminApiDir["api/admin/"]:::backend
                AdminAlbumsApi["albums/route.ts"]:::backend
                AdminLoginApi["login/route.ts"]:::backend
                AdminLogoutApi["logout/route.ts"]:::backend
                AdminVerifyApi["verify/route.ts"]:::backend
            end
            ConfigDb["config/database.ts"]:::backend
            InitMongo["config/initMongoDB.ts"]:::backend
        end
        StaticServer["Static Server (public/)"]:::backend
    end

    %% Data Services
    subgraph "Data Layer & Utilities"
        direction TB
        MongoClient["src/lib/mongodb.ts"]:::data
        DatabaseHelper["src/lib/database.ts"]:::data
        UploadUtil["src/lib/upload.ts"]:::data
        ClientCache["src/lib/clientCache.ts"]:::data
        AlbumCache["src/lib/albumCache.ts"]:::data
        CacheDebug["src/lib/cacheDebug.ts"]:::data
        FetchCache["src/lib/fetchWithCache.ts"]:::data
        AudioContext["src/lib/AudioContext.tsx"]:::data
    end

    %% Storage
    subgraph "File Storage" 
        direction TB
        PublicUploads["public/uploads/"]:::storage
        LocalUploads["storage/uploads/"]:::storage
    end

    %% Scripts & Config
    subgraph "Scripts & Config"
        direction TB
        InitScript["scripts/init-db.js"]:::backend
        SeedAdmin["scripts/seed-admins.js"]:::backend
        TestConn["scripts/test-connection.js"]:::backend
        NextConfig["next.config.ts"]:::backend
        TailwindConfig["tailwind.config.js"]:::backend
        PostCss["postcss.config.mjs"]:::backend
        EslintConfig["eslint.config.mjs"]:::backend
    end

    %% Relationships
    Browser -->|"Requests Pages"| AppDir
    Browser -->|"fetch /api/... "| ApiDir
    AppDir -->|uses| Middleware
    ApiDir -->|calls| MongoClient
    MongoClient -->|connects to| MongoDB["MongoDB"]:::data
    UploadApi -->|saves file| UploadUtil
    UploadUtil -->|writes to| LocalUploads
    LocalUploads -->|served as| PublicUploads
    PublicUploads -->|served by| StaticServer
    StaticServer -->|delivered via| Vercel
    AnalyticsApi -.->|"async event"| MongoDB
    Browser -->|static assets| PublicUploads
    Vercel -->|deploys| NextJSCluster["Next.js Server"]:::backend

    %% Click Events
    click AppDir "https://github.com/dodao123/cout-love/tree/main/src/app/"
    click Layout "https://github.com/dodao123/cout-love/blob/main/src/app/layout.tsx"
    click Globals "https://github.com/dodao123/cout-love/blob/main/src/app/globals.css"
    click Home "https://github.com/dodao123/cout-love/blob/main/src/app/page.tsx"
    click Gallery "https://github.com/dodao123/cout-love/blob/main/src/app/gallery/page.tsx"
    click Category "https://github.com/dodao123/cout-love/blob/main/src/app/category.tsx"
    click PrevSlug "https://github.com/dodao123/cout-love/blob/main/src/app/prevSlug/[slug]/page.tsx"
    click AlbumPage "https://github.com/dodao123/cout-love/blob/main/src/app/[slug]/page.tsx"
    click NotePage "https://github.com/dodao123/cout-love/blob/main/src/app/[slug]/Note/page.tsx"
    click AdminDir "https://github.com/dodao123/cout-love/tree/main/src/app/admin/"
    click AdminLogin "https://github.com/dodao123/cout-love/blob/main/src/app/admin/Login/page.tsx"
    click AdminAdd "https://github.com/dodao123/cout-love/blob/main/src/app/admin/addAlbum/page.tsx"
    click AdminManage "https://github.com/dodao123/cout-love/blob/main/src/app/admin/managerAlbum/page.tsx"
    click ApiDir "https://github.com/dodao123/cout-love/tree/main/src/app/api/"
    click AlbumsApi "https://github.com/dodao123/cout-love/tree/main/src/app/api/albums/"
    click SingleAlbumApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/albums/[slug]/route.ts"
    click NotesApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/notes/route.ts"
    click UploadApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/upload/route.ts"
    click AnalyticsApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/analytics/route.ts"
    click CategoriesApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/categories/route.ts"
    click HealthApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/health/route.ts"
    click AdminApiDir "https://github.com/dodao123/cout-love/tree/main/src/app/api/admin/"
    click AdminAlbumsApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/admin/albums/route.ts"
    click AdminLoginApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/admin/login/route.ts"
    click AdminLogoutApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/admin/logout/route.ts"
    click AdminVerifyApi "https://github.com/dodao123/cout-love/blob/main/src/app/api/admin/verify/route.ts"
    click ConfigDb "https://github.com/dodao123/cout-love/blob/main/src/app/api/config/database.ts"
    click InitMongo "https://github.com/dodao123/cout-love/blob/main/src/app/api/config/initMongoDB.ts"
    click MongoClient "https://github.com/dodao123/cout-love/blob/main/src/lib/mongodb.ts"
    click DatabaseHelper "https://github.com/dodao123/cout-love/blob/main/src/lib/database.ts"
    click UploadUtil "https://github.com/dodao123/cout-love/blob/main/src/lib/upload.ts"
    click ClientCache "https://github.com/dodao123/cout-love/blob/main/src/lib/clientCache.ts"
    click AlbumCache "https://github.com/dodao123/cout-love/blob/main/src/lib/albumCache.ts"
    click CacheDebug "https://github.com/dodao123/cout-love/blob/main/src/lib/cacheDebug.ts"
    click FetchCache "https://github.com/dodao123/cout-love/blob/main/src/lib/fetchWithCache.ts"
    click AudioContext "https://github.com/dodao123/cout-love/blob/main/src/lib/AudioContext.tsx"
    click PublicUploads "https://github.com/dodao123/cout-love/tree/main/public/uploads/"
    click LocalUploads "https://github.com/dodao123/cout-love/tree/main/storage/uploads/"
    click InitScript "https://github.com/dodao123/cout-love/blob/main/scripts/init-db.js"
    click SeedAdmin "https://github.com/dodao123/cout-love/blob/main/scripts/seed-admins.js"
    click TestConn "https://github.com/dodao123/cout-love/blob/main/scripts/test-connection.js"
    click NextConfig "https://github.com/dodao123/cout-love/blob/main/next.config.ts"
    click TailwindConfig "https://github.com/dodao123/cout-love/blob/main/tailwind.config.js"
    click PostCss "https://github.com/dodao123/cout-love/blob/main/postcss.config.mjs"
    click EslintConfig "https://github.com/dodao123/cout-love/blob/main/eslint.config.mjs"

    %% Styles
    classDef frontend fill:#a2f5a2,stroke:#23a023,color:#000
    classDef backend fill:#a2d0f5,stroke:#2373a0,color:#000
    classDef data fill:#f5d3a2,stroke:#a05a23,color:#000
    classDef storage fill:#f5f0a2,stroke:#a09c23,color:#000
    classDef external fill:#d0d0d0,stroke:#808080,color:#000
```
