# projectunicorn25/timepulse architecture

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

- Interactive diagram: https://gitdiagram.com/projectunicorn25/timepulse
- Repository: https://github.com/projectunicorn25/timepulse

## Overview

##### Project type and purpose
- TimePulse is a full-stack, collaborative time-tracking web application.
- Built with Next.js App Router (v14), React Server & Client Components, Supabase (PostgreSQL, Auth, Realtime), Tailwind CSS, and Zod for schema validation.
- Provides contractor and manager workflows: log time, submit for approval, realtime updates, audit trails, role-based security (RLS).

##### File structure
- **app/** – Next.js App Router directory
- (auth) – login/signup pages
- admin – manager dashboard pages and API route at `/admin/api/status/route.ts`
- dashboard – contractor pages (entry form, list)
- actions.ts – server-side form actions with Zod
- layout.tsx & providers.tsx – root layout, theme & toast providers
- middleware.ts – route protection
- **components/** – shared UI components (Navbar, Buttons, Backgrounds)
- **lib/** – Supabase client initializers (`supabaseClient.ts`, `supabaseServer.ts`), utility functions, Zod schemas (`validation.ts`)
- **supabase.sql** – database schema and RLS policies
- Config & tooling – `next.config.mjs`, `tailwind.config.ts`, ESLint, PostCSS, TS config, deployment scripts

##### README for architectural insights
- Auth via Supabase Auth (OAuth and email/password)
- Realtime WebSocket updates using Supabase’s realtime engine
- Approval workflow enforced by database policies and server-side actions
- Optimistic UI patterns, loading states and toasts handled in React components

##### Elements
- Clear rectangular blocks for each component (Browser UI, Next.js Server, Supabase Auth, Supabase DB, Supabase Realtime)
- UI components (e.g., light blue)
- Server/API (e.g., green)
- Data stores/services (e.g., orange)
- Labels for key modules (e.g., `app/dashboard`, `app/admin/api/status`, `lib/supabaseServer`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        direction TB
        UI["React UI (Next.js)"]:::frontend
        UI -->|HTTPS| NextServer
    end

    %% Next.js App Server Layer
    subgraph "Next.js App Server"
        direction TB
        NextServer["Next.js App Server"]:::server

        subgraph "Auth Segment"
            direction TB
            AuthLogin["Login Page"]:::frontend
            AuthSignup["Signup Page"]:::frontend
            AuthCallback["Auth Callback Route"]:::api
        end

        subgraph "Dashboard Segment"
            direction TB
            DashHome["Dashboard Home"]:::frontend
            EntryForm["Entry Form"]:::frontend
            EntryList["Entry List"]:::frontend
            DashLoading["Loading State"]:::frontend
        end

        subgraph "Admin Segment"
            direction TB
            AdminUI["Admin UI"]:::frontend
            AdminClient["Admin Client Component"]:::frontend
            APIStatus["Admin API Route"]:::api
        end

        subgraph "Core Server Modules"
            direction TB
            Actions["Server Actions (Zod)"]:::server
            Layout["Root Layout"]:::server
            Providers["Theme & Toast Providers"]:::server
            Middleware["Route Protection Middleware"]:::infra
        end

        NextServer --> AuthLogin
        NextServer --> AuthSignup
        NextServer --> AuthCallback
        NextServer --> DashHome
        NextServer --> EntryForm
        NextServer --> EntryList
        NextServer --> DashLoading
        NextServer --> AdminUI
        NextServer --> AdminClient
        NextServer --> APIStatus
        NextServer --> Actions
        NextServer --> Layout
        NextServer --> Providers
        NextServer --> Middleware
    end

    %% Lib Layer
    subgraph "Library (lib)"
        direction TB
        SupaClient["Supabase Browser Client"]:::server
        SupaServer["Supabase Server Client"]:::server
        Utils["Utility Functions"]:::server
        Validation["Zod Schemas & Validation"]:::server
        SupaClient --> SupaServer
    end

    %% Supabase Backend Layer
    subgraph "Supabase"
        direction TB
        AuthService["Auth Service"]:::datasvc
        Realtime["Realtime Service (WebSocket)"]:::datasvc
        DB["PostgreSQL DB (RLS & Audit Trail)"]:::database
    end

    %% Config & Tooling
    subgraph "Config & Tooling"
        direction TB
        NextConfig["Next.js Config"]:::infra
        TailwindConfig["Tailwind Config"]:::infra
        ESLintConfig["ESLint Config"]:::infra
        PostCSSConfig["PostCSS Config"]:::infra
        TSConfig["TypeScript Config"]:::infra
    end

    %% Shared Components
    Components["Shared UI Components"]:::frontend

    %% Database Schema File
    SupaSQL["Database Schema & RLS (supabase.sql)"]:::database

    %% Connections
    NextServer -->|uses| SupaServer
    NextServer -->|uses| SupaClient
    NextServer -->|uses| Validation
    Actions -->|validates| Validation
    AuthCallback -->|auth callback| AuthService
    NextServer -->|queries| DB
    APIStatus -->|queries| DB
    DashHome -->|fetch data| NextServer
    UI -->|WebSocket| Realtime
    Realtime -->|push updates| UI
    Middleware -->|enforces| NextServer
    Components -->|used by| UI
    Layout -->|wraps| UI
    Providers -->|wraps| UI

    %% Click Events
    click AuthLogin "https://github.com/projectunicorn25/timepulse/blob/main/app/(auth)/login/page.tsx"
    click AuthSignup "https://github.com/projectunicorn25/timepulse/blob/main/app/(auth)/signup/page.tsx"
    click AuthCallback "https://github.com/projectunicorn25/timepulse/blob/main/app/auth/callback/route.ts"
    click EntryForm "https://github.com/projectunicorn25/timepulse/blob/main/app/dashboard/EntryForm.tsx"
    click EntryList "https://github.com/projectunicorn25/timepulse/blob/main/app/dashboard/EntryList.tsx"
    click DashHome "https://github.com/projectunicorn25/timepulse/blob/main/app/dashboard/page.tsx"
    click DashLoading "https://github.com/projectunicorn25/timepulse/blob/main/app/dashboard/loading.tsx"
    click AdminUI "https://github.com/projectunicorn25/timepulse/blob/main/app/admin/page.tsx"
    click AdminClient "https://github.com/projectunicorn25/timepulse/blob/main/app/admin/AdminClient.tsx"
    click APIStatus "https://github.com/projectunicorn25/timepulse/blob/main/app/admin/api/status/route.ts"
    click Actions "https://github.com/projectunicorn25/timepulse/blob/main/app/actions.ts"
    click Layout "https://github.com/projectunicorn25/timepulse/blob/main/app/layout.tsx"
    click Providers "https://github.com/projectunicorn25/timepulse/blob/main/app/providers.tsx"
    click Components "https://github.com/projectunicorn25/timepulse/tree/main/components/"
    click SupaClient "https://github.com/projectunicorn25/timepulse/blob/main/lib/supabaseClient.ts"
    click SupaServer "https://github.com/projectunicorn25/timepulse/blob/main/lib/supabaseServer.ts"
    click Utils "https://github.com/projectunicorn25/timepulse/blob/main/lib/utils.ts"
    click Validation "https://github.com/projectunicorn25/timepulse/blob/main/lib/validation.ts"
    click SupaSQL "https://github.com/projectunicorn25/timepulse/blob/main/supabase.sql"
    click NextConfig "https://github.com/projectunicorn25/timepulse/blob/main/next.config.mjs"
    click TailwindConfig "https://github.com/projectunicorn25/timepulse/blob/main/tailwind.config.ts"
    click ESLintConfig "https://github.com/projectunicorn25/timepulse/blob/main/.eslintrc.json"
    click PostCSSConfig "https://github.com/projectunicorn25/timepulse/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/projectunicorn25/timepulse/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0284C7,stroke-width:1px
    classDef server fill:#D1FAE5,stroke:#047857,stroke-width:1px
    classDef api fill:#F0F9FF,stroke:#0C4A6E,stroke-width:1px
    classDef datasvc fill:#FFEDD5,stroke:#C2410C,stroke-width:1px
    classDef database fill:#FFE7D9,stroke:#C2410C,stroke-width:1px
    classDef infra fill:#F3F4F6,stroke:#4B5563,stroke-width:1px
```
