# gxjakkap/cc36staffapp architecture

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

- Interactive diagram: https://gitdiagram.com/gxjakkap/cc36staffapp
- Repository: https://github.com/gxjakkap/cc36staffapp

## Overview

##### Project Type and Purpose
- This is a full-stack web application.
- Its primary purpose is managing applicants and participant data. It includes features for admin management (adding/editing/deleting staff), user authentication, and various dashboards.
- The README and file structure indicate integration with migration management (drizzle-staff) and authentication via Better-Auth.

##### Main Components
a. Frontend Layer:
- Next.js Pages and Components: Represented by the “src/app”, “src/components”, and “src/pages (if any)” directories.
- Separate routing logic for authenticated (“(authed)”) versus unauthenticated (“(unauth)”) views.
- UI elements, shared components, and layout files – highlight that there’s a heavy use of React components and UI primitives (found in src/components/ui).

b. Backend/API Layer:
- API Endpoints: Found in “src/app/api/…” using Next.js API routes (such as “[...all]/route.ts” under auth).
- Server-side business logic (e.g., authentication actions, migrations) including integration with Better-Auth.
- Utilization of server actions within "src/app/(authed)" directories.

c. Data Access and Database Layer:
- Database configuration and schema: The “src/db” directory holds code related to setting up the database schema and performing queries.
- Drizzle ORM and migration scripts: The “drizzle.config.ts”, “drizzle.staff.config.ts”, and the “drizzle-staff” directory (with SQL migration files and meta snapshots) are key parts that manage database migrations for live and development DBs.
- The local development database is managed via Docker (using compose-db.yml and docker-compose.yml) and Supabase is used in production.

d. Authentication & External Services:
- Better-Auth integration: Noted by environment variables in the README and migration commands related to @better-auth/cli.
- External storage and services (Supabase and S3) for storage and database connectivity.

e. DevOps and CI/CD:
- GitHub workflows (in .github/workflows) and Docker-related files (Dockerfile, docker-compose.yml) to manage build, deployment, and development processes.

##### Relationships and Data Flow
- End-users interacting with the frontend (different flows for unauthenticated (login) and authenticated users).
- The frontend (Next.js client and server components) communicating with API endpoints for tasks such as authentication, data management, and performing actions on staff/student data.
- The API layer interacting with the database through the Drizzle ORM abstraction and migrations managed by the “drizzle-staff” scripts.
- External authentication services (via Better-Auth) and storage/database provided by Supabase and S3.
- CI/CD pipelines triggering tests and builds via GitHub Workflows.

##### Architectural Patterns & Design Principles
- Separation of concerns is evident: the UI is clearly separated from business logic and database access.
- The file-based routing of Next.js is used to segregate authenticated routes from unauthenticated ones.
- MVC/MVP-like principles can be inferred; while not explicitly strictly model-view-controller, clear boundaries are maintained between views (React components), controllers (Next.js API routes and server actions), and models (database schema and migration scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User"]:::external

    subgraph "Frontend Layer"
        FS1["Next.js Pages"]:::frontend
        FS2["React Components"]:::frontend
        FS3["Unauthenticated Views"]:::frontend
        FS4["Authenticated Layout"]:::frontend
        FS5["Login Page"]:::frontend
    end

    subgraph "Backend/API Layer"
        API["API Endpoints"]:::backend
    end

    subgraph "Database Layer"
        DB["DB Directory"]:::db
        DB1["DB Index"]:::db
        DB2["DB Schema"]:::db
        DB3["Staff Schema"]:::db
        DC["Drizzle Config"]:::db
        DSC["Drizzle Staff Config"]:::db
        DM["Drizzle Migrations"]:::db
    end

    subgraph "Authentication & External Services"
        AUTH1["Better-Auth Client"]:::auth
        AUTH2["Better-Auth Utility"]:::auth
        EXTS["External Storage (Supabase/S3)"]:::auth
    end

    subgraph "DevOps & CI/CD"
        GH["GitHub Workflows"]:::devops
        DF["Dockerfile"]:::devops
        DCY["Docker Compose"]:::devops
        CDB["Compose DB"]:::devops
    end

    subgraph "Utility Modules"
        ERR["Error Handling"]:::util
        FORM["Formatter"]:::util
        UT["Utility Functions"]:::util
    end

    U --> FS1
    U --> FS2
    U --> FS3
    U --> FS5

    FS1 -->|"fetches"| API
    FS2 -->|"triggers_actions"| API
    FS3 -->|"redirects_to"| FS5
    FS5 -->|"authenticates"| API

    API -->|"queries"| DB
    API -->|"queries"| DB1
    API -->|"queries"| DB2
    API -->|"queries"| DB3
    API -->|"reads_config"| DC
    API -->|"reads_config"| DSC
    API -->|"executes"| DM
    API -->|"calls_auth"| AUTH1
    API -->|"calls_auth"| AUTH2
    API -->|"stores_data"| EXTS

    GH --- API
    GH --- FS1
    DF --- API
    DCY --- API
    CDB --- DB

    ERR --- FS2
    FORM --- FS2
    UT --- API

    click FS1 "https://github.com/gxjakkap/cc36staffapp/tree/main/src/app"
    click FS2 "https://github.com/gxjakkap/cc36staffapp/tree/main/src/components"
    click FS3 "https://github.com/gxjakkap/cc36staffapp/tree/main/src/app/(unauth)"
    click FS4 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/app/(authed)/layout.tsx"
    click FS5 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/app/(unauth)/login/page.tsx"
    click API "https://github.com/gxjakkap/cc36staffapp/blob/main/src/app/api/auth/[...all]/route.ts"
    click DB "https://github.com/gxjakkap/cc36staffapp/tree/main/src/db"
    click DB1 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/db/index.ts"
    click DB2 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/db/schema.ts"
    click DB3 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/db/staff-schema.ts"
    click DC "https://github.com/gxjakkap/cc36staffapp/blob/main/drizzle.config.ts"
    click DSC "https://github.com/gxjakkap/cc36staffapp/blob/main/drizzle.staff.config.ts"
    click DM "https://github.com/gxjakkap/cc36staffapp/tree/main/drizzle-staff"
    click AUTH1 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/lib/auth-client.ts"
    click AUTH2 "https://github.com/gxjakkap/cc36staffapp/blob/main/src/lib/auth.ts"
    click GH "https://github.com/gxjakkap/cc36staffapp/blob/main/.github/workflows/build-staff.yml"
    click DF "https://github.com/gxjakkap/cc36staffapp/tree/main/Dockerfile"
    click DCY "https://github.com/gxjakkap/cc36staffapp/blob/main/docker-compose.yml"
    click CDB "https://github.com/gxjakkap/cc36staffapp/blob/main/compose-db.yml"
    click ERR "https://github.com/gxjakkap/cc36staffapp/blob/main/src/lib/errors.ts"
    click FORM "https://github.com/gxjakkap/cc36staffapp/blob/main/src/lib/formatter.ts"
    click UT "https://github.com/gxjakkap/cc36staffapp/blob/main/src/lib/utils.ts"

    classDef frontend fill:#fdd,stroke:#e34,stroke-width:2px;
    classDef backend fill:#ddf,stroke:#55f,stroke-width:2px;
    classDef db fill:#dfd,stroke:#393,stroke-width:2px;
    classDef auth fill:#ffd,stroke:#cc0,stroke-width:2px;
    classDef devops fill:#fef,stroke:#fa0,stroke-width:2px;
    classDef util fill:#eef,stroke:#999,stroke-width:2px;
    classDef external fill:#ddd,stroke:#000,stroke-width:2px;
    class U external;
```
