# lexiesm/dccommit-backend architecture

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

- Interactive diagram: https://gitdiagram.com/lexiesm/dccommit-backend
- Repository: https://github.com/lexiesm/dccommit-backend

## Overview

##### Project type and purpose
- This is a TypeScript-based backend API service (built with Express) whose primary role is to provide RESTful endpoints for posts, comments, users, reports, and verification flows.
- Authentication is delegated to Clerk (via the `src/api/auth-clerk/middleware.ts`).
- Data persistence is handled through Prisma ORM against a PostgreSQL database (likely hosted on Supabase, as indicated by the `supabase/` folder and `schema.prisma`).
- You plan to connect this API to a Next.js frontend that also uses Clerk for user sessions.

##### File structure
Top-level directories:
- src/api/auth-clerk: auth middleware integrating Clerk
- src/api/routes: Express route definitions for each resource
- src/api/controllers: business logic per resource
- src/lib/prisma.ts: Prisma client instantiation
- prisma/: database schema and migrations
- supabase/: hosting/config for Supabase backend
- dist/: compiled output (mirrors src/)
- app.ts / index.ts: Express app setup and server entrypoint
- routes.ts: central route‐mounting

##### Key insights from README
- Minimal README: points to a Postman collection for full API documentation.
- Confirms this is purely an API; no frontend code here.

##### Main components
a. Frontend Layer
- Next.js application
- Clerk React SDK for UI-side authentication flows (sign-in, sign-up)
b. Authentication Service
- Clerk.io (external SaaS)
- Clerk Identity API (verifies JWTs, issues sessions)
c. API Gateway / Backend
- Express.js server (`src/app.ts`, `src/index.ts`)
- Auth middleware (`auth-clerk/middleware.ts`) validating Clerk tokens
- Route handlers (`src/api/routes/*.ts`)
- Controllers (`src/api/controllers/*.ts`) containing business logic
- Prisma ORM client (`src/lib/prisma.ts`)
d. Database Layer
- PostgreSQL instance (hosted on Supabase)
- Prisma migrations / schema (`prisma/schema.prisma`, `prisma/migrations/`)
e. External Tools
- Postman collection for API testing
- GitHub Actions (`.github/workflows/render.yml`) for CI/CD

##### Relationships and data flows
1. User interacts with Next.js UI → triggers Clerk frontend SDK to authenticate → Clerk issues JWT/session.
2. Next.js makes API calls to Express endpoints, sending the Clerk JWT in the Authorization header.
3. Express auth middleware intercepts requests, calls Clerk API to validate tokens → attaches user context.
4. Authenticated request flows through route → controller → Prisma for DB queries/updates.
5. Prisma communicates with the PostgreSQL database on Supabase.
6. Controller returns response; Express sends JSON back to Next.js.

##### Architectural patterns and design principles
- Layered architecture: Presentation (Next.js), Application/API (Express), Domain/Services (controllers), Data (Prisma/DB).
- Separation of concerns: routes only dispatch to controllers; controllers orchestrate ORM calls.
- Middleware pattern: auth-clerk middleware decouples authentication logic.
- Infrastructure as code: Prisma migrations, Supabase config, CI workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextJS["Next.js Application"]:::frontend
        ClerkSDK["Clerk React SDK"]:::frontend
    end

    %% Authentication Layer
    subgraph "Authentication Service"
        direction TB
        ClerkExt["Clerk.io (External SaaS)"]:::auth
        ClerkAPI["Clerk Identity API"]:::auth
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        subgraph "Express Server"
            direction TB
            App["Express App (app.ts)"]:::api
            Index["Server Entry (index.ts)"]:::api
        end
        subgraph "Auth Middleware"
            direction TB
            Middleware["Clerk Auth Middleware (middleware.ts)"]:::api
        end
        subgraph "API Routes"
            direction TB
            PostRoutes["post.routes.ts"]:::api
            CommentRoutes["comment.routes.ts"]:::api
            UserRoutes["user.routes.ts"]:::api
            ReportRoutes["report.routes.ts"]:::api
            VerificationRoutes["verification.routes.ts"]:::api
            TestRoutes["test.routes.ts"]:::api
        end
        subgraph "Controllers"
            direction TB
            PostCtrl["post.controller.ts"]:::api
            CommentCtrl["comment.controller.ts"]:::api
            UserCtrl["user.controller.ts"]:::api
            ReportCtrl["report.controller.ts"]:::api
            VerificationCtrl["verification.controller.ts"]:::api
        end
        PrismaClient["Prisma Client (prisma.ts)"]:::api
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Schema["schema.prisma"]:::data
        Migrations["migrations/"]:::data
        Postgres["PostgreSQL Database"]:::data
        SupabaseConfig["supabase/config.toml"]:::data
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Postman["API DCCommits.postman_collection.json"]:::tool
        CICD[".github/workflows/render.yml"]:::tool
    end

    %% Connections
    NextJS -->|"uses SDK to auth"| ClerkSDK
    ClerkSDK -->|"auth requests"| ClerkAPI
    ClerkAPI -->|"issues JWT"| NextJS
    NextJS -->|"sends requests with JWT"| App
    App -->|intercepts| Middleware
    Middleware -->|"validates token"| ClerkAPI
    App -->|"mounts routes via routes.ts"| PostRoutes
    App -->|"mounts routes via routes.ts"| CommentRoutes
    App -->|"mounts routes via routes.ts"| UserRoutes
    App -->|"mounts routes via routes.ts"| ReportRoutes
    App -->|"mounts routes via routes.ts"| VerificationRoutes
    App -->|"mounts routes via routes.ts"| TestRoutes
    PostRoutes -->|"calls"| PostCtrl
    CommentRoutes -->|"calls"| CommentCtrl
    UserRoutes -->|"calls"| UserCtrl
    ReportRoutes -->|"calls"| ReportCtrl
    VerificationRoutes -->|"calls"| VerificationCtrl
    PostCtrl -->|"queries"| PrismaClient
    CommentCtrl -->|"queries"| PrismaClient
    UserCtrl -->|"queries"| PrismaClient
    ReportCtrl -->|"queries"| PrismaClient
    VerificationCtrl -->|"queries"| PrismaClient
    PrismaClient -->|"reads/writes"| Postgres
    PrismaClient -->|"schema from"| Schema
    PrismaClient -->|"migrations from"| Migrations

    %% Side Tools Connections
    App ---|CI/CD deployment| CICD
    App ---|tested via| Postman

    %% Click Events
    click App "https://github.com/lexiesm/dccommit-backend/blob/main/src/app.ts"
    click Index "https://github.com/lexiesm/dccommit-backend/blob/main/src/index.ts"
    click Middleware "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/auth-clerk/middleware.ts"
    click PostRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/post.routes.ts"
    click CommentRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/comment.routes.ts"
    click UserRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/user.routes.ts"
    click ReportRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/report.routes.ts"
    click VerificationRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/verification.routes.ts"
    click TestRoutes "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/routes/test.routes.ts"
    click PostCtrl "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/controllers/post.controller.ts"
    click CommentCtrl "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/controllers/comment.controller.ts"
    click UserCtrl "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/controllers/user.controller.ts"
    click ReportCtrl "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/controllers/report.controller.ts"
    click VerificationCtrl "https://github.com/lexiesm/dccommit-backend/blob/main/src/api/controllers/verification.controller.ts"
    click PrismaClient "https://github.com/lexiesm/dccommit-backend/blob/main/src/lib/prisma.ts"
    click Schema "https://github.com/lexiesm/dccommit-backend/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/lexiesm/dccommit-backend/tree/main/prisma/migrations/"
    click SupabaseConfig "https://github.com/lexiesm/dccommit-backend/blob/main/supabase/config.toml"
    click CICD "https://github.com/lexiesm/dccommit-backend/blob/main/.github/workflows/render.yml"
    click Postman "https://github.com/lexiesm/dccommit-backend/blob/main/API DCCommits.postman_collection.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef auth fill:#90EE90,stroke:#333,stroke-width:1px
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#9370DB,stroke:#333,stroke-width:1px
    classDef tool fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
