# th-ndang/sv-free architecture

> Architecture diagram of the GitHub repository th-ndang/sv-free, 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/th-ndang/sv-free
- Repository: https://github.com/th-ndang/sv-free

## Overview

##### Main Components
- Client/Browser: Represent the end-user’s web browser where the SVFree UI runs.
- Next.js Frontend: This includes both the main site (found under app/(main)) and the admin panel (under app/admin). Each of these contains several pages, components, and layouts.
- API Routes / Backend: Next.js API routes are located in app/(main)/api, app/api, and other endpoint directories (e.g., for auth, document download, storage, etc.). These routes encapsulate authentication, data fetching, file handling, and other business logic.
- Database: The presence of DrizzleORM, SQL migration files (in the drizzle folder), and schema definitions (under lib/db and drizzle/meta) indicate that database interactions are an integral part of the backend.
- Supporting Libraries & Utilities: Components such as authentication modules (in lib/auth), query providers (using Tanstack Query), utility files, and state management (in lib/states) which glue together the application logic.
- External and UI Libraries: TailwindCSS for styling, Shadcn UI components, and additional components found in the “components” directory, used for both demonstration and actual UI construction.

##### Relationships and Interactions
- The Client (browser) sends requests (HTTP/HTTPS) to the Next.js application server.
- Next.js serves dynamic pages via SSR (or static rendering where applicable) that include client-side components.
- User interactions (such as signing in, searching or uploading documents) result in API calls hitting the Next.js API routes.
- API endpoints then interact with the Database through DrizzleORM for storing, retrieving, or updating data.
- Authentication flows (found within app/(main)/api/auth and lib/auth) ensure secure access to both the main and admin contexts.
- Library integrations (Tanstack Query, etc.) handle data fetching and state synchronization between client and server.

##### Architectural Patterns and Design Principles
- File-Based Routing & Module Separation: Next.js organizes the project by feature (main area vs. admin area) and by technical role (API routes vs. UI components).
- Separation of Concerns: Components are separated into UI, business logic (in the API routes), and database access (managed by DrizzleORM).
- Reusable Components & Themability: With a dedicated components folder (including both common UI elements and demo versions) and theme-related modules (components/active-theme.tsx, lib/themes.ts), the project illustrates modularity and shared design elements.
- Code Quality & DevOps Integration: The pre-commit hooks, linting configuration (.lintstagedrc, .prettierignore, etc.), and GitHub workflows show an integrated CI/CD pipeline supporting the overall architecture.

##### Instructing the Principal Software Engineer
- Clear labels for each of the major components: Client, Next.js Frontend (Main & Admin), API Endpoints, Database, and third-party integrations.
- Browser → Next.js Server (Page Requests, API Calls)
- Next.js API Routes → Database (Data queries and updates)
- Presentation Layer (UI components, pages, layouts)
- Business Logic Layer (API routes, authentication flows)
- Data Layer (database accesses via DrizzleORM)
- Annotations or notes detailing frameworks and libraries involved, such as Next.js, TailwindCSS, Shadcn, Tanstack Query, and DrizzleORM.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLIENT("Browser / Client"):::client
    end

    %% Next.js Server Layer
    subgraph "Next.js Server"
        subgraph "Frontend"
            NEXT_MAIN("Main Site (Next.js Frontend)"):::frontend
            NEXT_ADMIN("Admin Panel (Next.js Frontend)"):::frontend
        end
        subgraph "API Endpoints"
            API_MAIN("Main API Routes"):::api
            API_OTHER("Other API Endpoints"):::api
            API_AUTH("Auth API Endpoints"):::api
            AUTH_LIB("Authentication Library"):::api
        end
    end

    %% Database Layer
    subgraph "Database Layer"
        DB_MIG("SQL Migration Files"):::database
        DB_SCHEMA("Schema & DB Logic"):::database
    end

    %% Supporting Libraries & Utilities
    subgraph "Supporting Libraries & Utilities"
        UI_MAIN("Main Site Components"):::frontend
        UI_ADMIN("Admin Components"):::frontend
        UI_SHARED("Shared/Demo Components"):::frontend
        TAILWIND("TailwindCSS Styling"):::frontend
        QUERY_STATE("Query & State Providers"):::utils
    end

    %% Connections from Client to Next.js Server
    CLIENT -->|"PageRequest"| NEXT_MAIN
    CLIENT -->|"AdminAccess"| NEXT_ADMIN
    CLIENT -->|"APIRequest"| API_MAIN
    CLIENT -->|"APIRequest"| API_OTHER
    CLIENT -->|"AuthRequest"| API_AUTH

    %% Connections within Next.js Server - Frontend uses supporting libraries
    NEXT_MAIN -->|"UsesComponents"| UI_MAIN
    NEXT_MAIN -->|"StateManagement"| QUERY_STATE
    NEXT_ADMIN -->|"UsesComponents"| UI_ADMIN
    NEXT_ADMIN -->|"StateManagement"| QUERY_STATE

    %% Connections from API Endpoints to Database
    API_MAIN -->|"DataAccess"| DB_SCHEMA
    API_OTHER -->|"DataAccess"| DB_SCHEMA
    API_AUTH -->|"DataAccess"| DB_SCHEMA
    API_AUTH -->|"AuthCalls"| AUTH_LIB

    %% Optionally linking shared UI and styling (used by both Frontend nodes)
    NEXT_MAIN --- UI_SHARED
    NEXT_ADMIN --- UI_SHARED
    NEXT_MAIN --- TAILWIND
    NEXT_ADMIN --- TAILWIND

    %% Click Events
    click NEXT_MAIN "https://github.com/th-ndang/sv-free/tree/main/app/(main)"
    click NEXT_ADMIN "https://github.com/th-ndang/sv-free/tree/main/app/admin"
    click API_MAIN "https://github.com/th-ndang/sv-free/tree/main/app/(main)/api"
    click API_OTHER "https://github.com/th-ndang/sv-free/tree/main/app/api"
    click API_AUTH "https://github.com/th-ndang/sv-free/tree/main/app/(main)/api/auth"
    click AUTH_LIB "https://github.com/th-ndang/sv-free/tree/main/lib/auth"
    click UI_MAIN "https://github.com/th-ndang/sv-free/tree/main/app/(main)/components"
    click UI_ADMIN "https://github.com/th-ndang/sv-free/tree/main/app/admin/components"
    click UI_SHARED "https://github.com/th-ndang/sv-free/tree/main/components"
    click TAILWIND "https://github.com/th-ndang/sv-free/tree/main/styles"
    click QUERY_STATE "https://github.com/th-ndang/sv-free/blob/main/components/query-provider.tsx"
    click DB_MIG "https://github.com/th-ndang/sv-free/tree/main/drizzle"
    click DB_SCHEMA "https://github.com/th-ndang/sv-free/tree/main/lib/db"

    %% Styles
    classDef client fill:#f9d6ac,stroke:#d35400,stroke-width:2px;
    classDef frontend fill:#dff0d8,stroke:#3c763d,stroke-width:2px;
    classDef api fill:#d0e1f9,stroke:#31708f,stroke-width:2px;
    classDef database fill:#f2dede,stroke:#a94442,stroke-width:2px;
    classDef utils fill:#d9edf7,stroke:#31708f,stroke-width:2px;
```
