# pieterbb/todostreak architecture

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

- Interactive diagram: https://gitdiagram.com/pieterbb/todostreak
- Repository: https://github.com/pieterbb/todostreak

## Overview

##### Main system components
- Client/Browser: Represents the user-facing layer, where users interact with the application.
- Next.js Frontend: The React-based UI built using Next.js (in the /src/app directory). This includes pages for todos, projects, topics, settings, profiles, etc. Distinguish between public pages, user profiles, and project pages.
- API Routes: Located under /src/app/api (for auth, projects, search, settings, todos, topics, users). These server-side endpoints handle data fetching, authentication workflows, and mutations.
- Database & ORM Layer: Prisma in the /prisma directory (with schema and seed files). This layer communicates with the Postgres database.
- External Services:
- Authentication Providers: NextAuth.js endpoints for social OAuth and magic link email authentication.
- Storage & Media: Cloudinary for image uploads.
- Email Service / SMTP server for sending authentication messages.
- (Optional) Third-party integrations such as Discord or Google OAuth.
- Utility Libraries & Hooks: Shared utilities in /src/lib and custom React hooks (in /src/hooks) that encapsulate business logic, state management via React Query, form handling, file uploads, etc.
- Configuration & Deployment: Files like next.config.js, Vercel integration snippets, Tailwind CSS configurations, and environment variable files (.env.example) that provide setup and deployment details.

##### Relationship and interactions
- The Browser communicates with the Next.js Frontend which renders the UI components. These components are built using React and styled with Tailwind CSS.
- When data is needed, the client makes calls (often via React Query and custom hooks) to the API routes. These API routes are internally structured under /src/app/api.
- The API routes use Prisma (via client code in /src/lib) to read from/write to the Postgres database.
- Authentication requests are handled by NextAuth.js (in /src/app/api/auth/...), which also interacts with external authentication providers (social OAuth, SMTP for magic links).
- Media uploads (e.g., user avatars, project images) integrate with Cloudinary.
- Additionally, utility hooks and components are shared across various parts of the frontend, ensuring modularization and reuse.

##### Architectural patterns and design principles
- Separation of Concerns: The structure clearly separates UI components, API endpoints, authentication logic, database interactions, and external services.
- Modular & Scalable: The directory organization (with different APIs for features like todos, projects, topics) indicates a modular design that can be extended as new features (e.g., forum enhancements or advanced notifications) are added.
- Use of Client and Server Components: With the Next.js app directory architecture, differentiate between components that run on the server and those on the client.
- Integration of Modern Libraries: Use of React Query for asynchronous server state and Zod for validation enforces type safety throughout the stack.

##### Including relevant technologies
- Next.js (React-based UI with Server and API routes)
- NextAuth.js for authentication flows
- Prisma as the ORM connecting to a Postgres database
- Tailwind CSS for styling
- React Query, React Hook Form, Zod for client-side data flow, form processing, and validations
- Cloudinary integration for media uploads

##### Elements
- Browser / Client
- Next.js Frontend (with nested UI components: pages, layouts, and widgets)
- API Server (highlight different sub-components like Auth API, Todos API, Projects API, Topics API)
- Database (Postgres via Prisma)
- External Services (Authentication Providers, SMTP, Cloudinary, optional third-party APIs like Discord/Google)
- Data/request flows from the Browser to the Frontend.
- API requests from the Frontend to the Backend (API routes) and responses back.
- Database queries from API endpoints to the Database.
- External calls from the API endpoints to third-party authentication services or media storage.
- Or add notes for key middleware logic such as authentication flows and data validations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Browser Layer
    A["Browser / Client"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        B["Next.js Frontend (UI Components & Pages)"]:::frontend
        I["Shared Utils (src/lib)"]:::frontend
        J["Custom Hooks (src/hooks)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        D["API Server (API Routes)"]:::backend
        D1["Auth API"]:::backend
        D2["Todos API"]:::backend
        D3["Projects API"]:::backend
        D4["Topics API"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        E["Database (Postgres via Prisma)"]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        F["Authentication Providers & SMTP"]:::external
        G["Cloudinary (Media Storage)"]:::external
    end

    %% Configuration & Deployment Layer
    subgraph "Configuration & Deployment"
        H1["Styling (Tailwind & Global CSS)"]:::config
        H2["Deployment & Config"]:::config
    end

    %% Data flow arrows
    A -->|"UIInteraction"| B
    B -->|"APICalls"| D
    B -->|"uses"| I
    B -->|"uses"| J
    D -->|"DBQuery"| E
    D1 -->|"AuthFlow"| F
    D1 -->|"DBAccess"| E
    D -->|"MediaUpload"| G
    H1 -->|"imports styles"| B
    H2 -->|"configures"| B
    H2 -->|"configures"| D

    %% Class Definitions for styling
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef database fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click B "https://github.com/pieterbb/todostreak/tree/main/src/app"
    click D "https://github.com/pieterbb/todostreak/tree/main/src/app/api"
    click D1 "https://github.com/pieterbb/todostreak/blob/main/src/app/api/auth/[...nextauth]"
    click E "https://github.com/pieterbb/todostreak/tree/main/prisma"
    click I "https://github.com/pieterbb/todostreak/tree/main/src/lib"
    click J "https://github.com/pieterbb/todostreak/tree/main/src/hooks"
    click H1 "https://github.com/pieterbb/todostreak/blob/main/tailwind.config.js"
    click H2 "https://github.com/pieterbb/todostreak/blob/main/next.config.js"
```
