# hayato33/pomo architecture

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

- Interactive diagram: https://gitdiagram.com/hayato33/pomo
- Repository: https://github.com/hayato33/pomo

## Overview

##### Main Components
- Frontend/UI:
– Next.js Application with App Router (located in the src/app directory).
– Pages for authentication (login, signup), timer functionality, timeline views, and analysis.
– Shared UI components (e.g., Cards, Charts, Tabs, Buttons, and other elements) grouped under directories such as src/app/_components and src/app/(auth)/_components.
- Backend/API:
– API endpoints under src/app/api, organized into modules for pomodoro, user, setting, and even a public pomodoro endpoint.
– Utility libraries and hooks that support endpoint logic (e.g., authHandlers, prisma integration).
- Database:
– Schema managed by Prisma (located in prisma/schema.prisma) which handles data persistence and likely represents users, pomodoro logs, settings, etc.
- External and Configuration Components:
– Authentication services and session management (observing hooks like useSupabaseSession).
– Configuration files (e.g., next.config.mjs, tsconfig.json, tailwind.config.ts) and styling (globals.css).
– Deployment and build configuration hinting at Vercel usage (as indicated in the README).

##### Relationships and Interactions
- The browser (client) interacts with the Next.js application, which serves UI pages (e.g., login, timer, analysis, timeline).
- UI components communicate with API endpoints where business logic is handled. For example:
– The Timer page calls API endpoints to record Pomodoro sessions.
– Analysis and Timeline pages fetch data from their respective endpoints.
- API endpoints then use Prisma (database module) to read/write user data, pomodoro logs, and settings.
- Authentication flows are handled through special libraries/hooks (using Supabase session and tailored auth schemas and handlers) that interact with both UI and secure API routes.
- The build configuration and styling (Tailwind, PostCSS) ensure a cohesive look and performance optimization.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The structure clearly separates UI components from API endpoints and backend services. Each module (auth, timer, analysis, timeline) is decoupled.
- Modular Design: Shared components (found in _components, _lib, _hooks) are abstracted for reusability across different pages, following DRY principles.
- API Gateway / Routing: API routes segmented by functionality make the design cleaner and easier to test.
- Use of Next.js App Router: Emphasizes a modern approach to building full-stack React applications with server-side rendering and client-side interactivity.

##### Relevant Technologies, Frameworks, and Libraries
- Next.js (for full-stack React application development)
- Prisma (for database schema and ORM)
- Tailwind CSS and PostCSS (for styling and UI optimization)
- Supabase integration (for authentication/session management)
- Vercel (for deployment, as suggested by the README)
- Additional components and libraries for handling charts, forms, and interactive UI behavior

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    Browser["Browser/Client"]:::frontend
    subgraph "Frontend Layer"
        FE["Next.js Frontend"]:::frontend
        Auth["Authentication Module"]:::frontend
        Timer["Timer Module"]:::frontend
        Analysis["Analysis Module"]:::frontend
        Timeline["Timeline Module"]:::frontend
    end

    %% API Endpoints Layer
    subgraph "API Endpoints"
        Pomodoro["Pomodoro API"]:::backend
        User["User API"]:::backend
        Setting["Setting API"]:::backend
        PublicPomodoro["Public Pomodoro API"]:::backend
    end

    %% Database
    Database["Prisma Database"]:::db

    %% Shared Utilities
    subgraph "Shared Utilities"
        SharedHooks["Shared Hooks"]:::utility
        SharedLib["Shared Lib"]:::utility
        APILib["API Lib"]:::utility
    end

    %% Configuration & External Services
    subgraph "Configuration & External Services"
        Config1["next.config.mjs"]:::config
        Config2["tsconfig.json"]:::config
        Config3["postcss.config.mjs"]:::config
        Config4["tailwind.config.ts"]:::config
        Globals["globals.css"]:::config
        Supabase["Supabase Session (useSupabaseSession)"]:::utility
    end

    %% Connections - Client to Frontend
    Browser --> FE

    %% Frontend Module Breakdown
    FE --> Auth
    FE --> Timer
    FE --> Analysis
    FE --> Timeline

    %% Module to API interactions
    Timer -->|"calls"| Pomodoro
    Timer -->|"mayCall"| PublicPomodoro
    Auth -->|"calls"| User
    Auth -->|"calls"| Setting
    Analysis -->|"fetches"| Pomodoro
    Timeline -->|"fetches"| Pomodoro

    %% API to Database
    Pomodoro --> Database
    User --> Database
    Setting --> Database
    PublicPomodoro --> Database

    %% Frontend utilization of Shared Utilities
    FE --> SharedHooks
    FE --> SharedLib

    %% API usage of utility libraries
    Pomodoro --> APILib
    User --> APILib
    Setting --> APILib
    PublicPomodoro --> APILib

    %% Configuration affecting Frontend
    Config1 --> FE
    Config2 --> FE
    Config3 --> FE
    Config4 --> FE
    Globals --> FE

    %% Supabase integration to Authentication & Shared Hooks
    Supabase --> Auth
    Supabase --> SharedHooks

    %% Class definitions for colours and styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef db fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef config fill:#ffcccb,stroke:#000,stroke-width:1px;
    classDef utility fill:#ffffcc,stroke:#000,stroke-width:1px;

    %% Click Events
    click FE "https://github.com/hayato33/pomo/tree/main/src/app"
    click Auth "https://github.com/hayato33/pomo/tree/main/src/app/(auth)"
    click Timer "https://github.com/hayato33/pomo/tree/main/src/app/timer"
    click Analysis "https://github.com/hayato33/pomo/tree/main/src/app/analysis"
    click Timeline "https://github.com/hayato33/pomo/tree/main/src/app/timeline"
    click Pomodoro "https://github.com/hayato33/pomo/tree/main/src/app/api/pomodoro"
    click User "https://github.com/hayato33/pomo/tree/main/src/app/api/user"
    click Setting "https://github.com/hayato33/pomo/tree/main/src/app/api/setting"
    click PublicPomodoro "https://github.com/hayato33/pomo/tree/main/src/app/api/public/pomodoro"
    click Database "https://github.com/hayato33/pomo/blob/main/prisma/schema.prisma"
    click SharedHooks "https://github.com/hayato33/pomo/tree/main/src/app/_hooks"
    click SharedLib "https://github.com/hayato33/pomo/tree/main/src/app/_lib"
    click APILib "https://github.com/hayato33/pomo/tree/main/src/app/api/_lib"
    click Config1 "https://github.com/hayato33/pomo/blob/main/next.config.mjs"
    click Config2 "https://github.com/hayato33/pomo/blob/main/tsconfig.json"
    click Config3 "https://github.com/hayato33/pomo/blob/main/postcss.config.mjs"
    click Config4 "https://github.com/hayato33/pomo/blob/main/tailwind.config.ts"
    click Globals "https://github.com/hayato33/pomo/blob/main/src/app/globals.css"
    click Supabase "https://github.com/hayato33/pomo/tree/main/src/app/_hooks"
```
