# oopsvincent/rhythme architecture

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

- Interactive diagram: https://gitdiagram.com/oopsvincent/rhythme
- Repository: https://github.com/oopsvincent/rhythme

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (App Router) that serves as a Personal Alignment System (“Rhythmé”).
- Front-end: React components styled with Tailwind CSS + shadcn/ui.
- Back-end: Supabase for Auth, PostgreSQL, and Storage.
- Hosted on Vercel.

##### File Structure
- **app/**: Next.js App Router pages (auth flows, dashboard, settings, legal, root pages).
- **components/**: Reusable UI pieces (auth forms, navbars, charts, date-pickers, tables, modals).
- **utils/supabase/** & **lib/utils.ts**: Supabase client and server wrappers, middleware.
- **store/** & **hooks/**: Zustand or custom stores; React hooks for UI state and OAuth.
- **public/**: Static assets (fonts).
- **middleware.ts**, **next.config.ts**: Edge configuration, redirects, authentication guards.
- **tsconfig.json**, **tailwind.config.ts**, **postcss.config.mjs**: Build and styling configuration.

##### README for Additional Insights
- Core Phase 1 features: secure signup/login, habits CRUD, journal entries, focus timer.
- Tech stack confirms Next.js SSR/SSG, React, Supabase (Auth, Postgres, Storage), TailwindCSS, Vercel.
- Future AI/ML integration planned but out of scope for current architecture.

##### Main Components
a. Frontend (Browser/Client)
- Next.js React pages & components
- JS/CSS Assets served via Vercel CDN
b. Next.js Server (Server-side Rendering & API Routes)
- App Router endpoints (app/auth/…/route.ts)
- Server Components invoking Supabase server client
c. Supabase
- Auth service
- PostgreSQL database
- Storage (if used for attachments)
d. State Management & Business Logic
- React hooks and Zustand stores (store/nav-store.ts, useDialogStore)
- Utility modules (lib/utils.ts, utils/getGreetings.ts)
e. External Services
- Vercel hosting & edge functions
- (Planned) AI/ML service via Python/FastAPI

##### Relationships and Data Flows
- Browser → Vercel CDN: static assets and hydration.
- Browser → Next.js Server “app” routes:
- Auth flows → Supabase Auth API
- API calls (getTasks.ts, auth.ts) → Supabase Postgres
- Next.js Server → Supabase: uses server-side client for secure data access.
- Browser (client components) → client-side Supabase library (utils/supabase/client.ts) for realtime hooks and storage.

##### Architectural Patterns and Design Principles
- **Separation of Concerns**:
- UI Layer: React components under components/ & sections/
- Routing Layer: Next.js file-based App Router
- Data Layer: Supabase wrappers + Zustand stores
- **Server-side Rendering / Incremental Static Regeneration** for landing, legal, marketing pages.
- **API Layer**: Next.js Route Handlers co-located under app/auth and app/actions.
- **Modular UI**: shadcn/ui primitives + custom components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["User Browser"]:::blue
        CDN["Vercel CDN"]:::orange
        subgraph "Next.js App Router Pages" 
            direction TB
            PagesDir["app/"]:::blue
            RootLayout["layout.tsx"]:::blue
            GlobalsCSS["globals.css"]:::blue
            AuthRoutes["(auth) Routes"]:::blue
            Marketing["(root)/(legal) Pages"]:::blue
            Dashboard["dashboard Pages"]:::blue
        end
        Components["UI Components (components/)"]:::blue
    end

    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        NextServer["Next.js Server\n(Route Handlers & SSR)"]:::green
        subgraph "API Layer (app/actions)"
            direction TB
            AuthActions["auth.ts"]:::green
            GetTasks["getTasks.ts"]:::green
        end
        subgraph "State & Utilities"
            direction TB
            Store["store/ & hooks/"]:::green
            SupabaseUtils["utils/supabase/"]:::green
            Helpers["lib/utils.ts & utils/getGreetings.ts"]:::green
        end
        Middleware["middleware.ts"]:::green
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        AuthService["Supabase Auth"]:::orange
        StorageService["Supabase Storage"]:::orange
        Postgres["PostgreSQL"]:::orange
    end

    %% Hosting
    Vercel["Vercel Hosting\n& Edge Functions"]:::orange

    %% Connections
    Browser -->|"HTTP/JSON"| CDN
    CDN -->|"Serves SSR/Assets"| NextServer
    Browser -->|"CSR Data Calls\nHTTP/JSON"| NextServer
    NextServer -->|"Server Client HTTP"| AuthService
    NextServer -->|"Server Client SQL"| Postgres
    NextServer -->|"Storage API"| StorageService
    Browser -->|"Realtime WS"| SupabaseUtils
    Browser -->|"Client Auth"| AuthService
    Browser -->|"Client Storage"| StorageService
    NextServer -->|"Middleware Guard"| Middleware
    NextServer -->|"API Calls"| AuthActions
    NextServer -->|"API Calls"| GetTasks
    NextServer -->|"Uses Stores & Hooks"| Store
    NextServer -->|"Uses Helpers"| Helpers
    Vercel --> NextServer

    %% Click Events
    click PagesDir "https://github.com/oopsvincent/rhythme/tree/master/app/"
    click RootLayout "https://github.com/oopsvincent/rhythme/blob/master/app/layout.tsx"
    click GlobalsCSS "https://github.com/oopsvincent/rhythme/blob/master/app/globals.css"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/auth/callback/route.ts"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/confirm/route.ts"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/login/actions.ts"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/login/page.tsx"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/logout/page.tsx"
    click AuthRoutes "https://github.com/oopsvincent/rhythme/blob/master/app/(auth)/signup/create/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(root)/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(root)/about/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(root)/features/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(root)/pricing/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(legal)/legal/privacy/page.tsx"
    click Marketing "https://github.com/oopsvincent/rhythme/blob/master/app/(legal)/legal/terms/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/habits/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/tasks/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/tasks/[slug]/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/journal/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/focus/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/goals/page.tsx"
    click Dashboard "https://github.com/oopsvincent/rhythme/blob/master/app/dashboard/layout.tsx"
    click AuthActions "https://github.com/oopsvincent/rhythme/blob/master/app/actions/auth.ts"
    click GetTasks "https://github.com/oopsvincent/rhythme/blob/master/app/actions/getTasks.ts"
    click Components "https://github.com/oopsvincent/rhythme/tree/master/components/"
    click Components "https://github.com/oopsvincent/rhythme/tree/master/components/ui/"
    click Store "https://github.com/oopsvincent/rhythme/blob/master/store/nav-store.ts"
    click Store "https://github.com/oopsvincent/rhythme/blob/master/store/useDialogStore.ts"
    click Store "https://github.com/oopsvincent/rhythme/blob/master/hooks/use-media-query.ts"
    click Store "https://github.com/oopsvincent/rhythme/blob/master/hooks/use-mobile.ts"
    click Store "https://github.com/oopsvincent/rhythme/blob/master/hooks/useOAuthError.ts"
    click SupabaseUtils "https://github.com/oopsvincent/rhythme/blob/master/utils/supabase/client.ts"
    click SupabaseUtils "https://github.com/oopsvincent/rhythme/blob/master/utils/supabase/server.ts"
    click SupabaseUtils "https://github.com/oopsvincent/rhythme/blob/master/utils/supabase/middleware.ts"
    click SupabaseUtils "https://github.com/oopsvincent/rhythme/blob/master/utils/supabase.ts"
    click Helpers "https://github.com/oopsvincent/rhythme/blob/master/lib/utils.ts"
    click Helpers "https://github.com/oopsvincent/rhythme/blob/master/utils/getGreetings.ts"
    click Middleware "https://github.com/oopsvincent/rhythme/blob/master/middleware.ts"
    click Middleware "https://github.com/oopsvincent/rhythme/blob/master/next.config.ts"
    click Middleware "https://github.com/oopsvincent/rhythme/blob/master/tailwind.config.ts"
    click Middleware "https://github.com/oopsvincent/rhythme/blob/master/postcss.config.mjs"
    click Browser "https://github.com/oopsvincent/rhythme/tree/master/public/"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#000
    classDef green fill:#d4edda,stroke:#000
    classDef orange fill:#fff3cd,stroke:#000
```
