# guillaumeca/circus-pes architecture

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

- Interactive diagram: https://gitdiagram.com/guillaumeca/circus-pes
- Repository: https://github.com/guillaumeca/circus-pes

## Overview

##### Project type and purpose
- Circus PES is a full-stack web application built with Next.js (React) on the frontend and Next.js API routes/trpc on the backend.
- It provides user-facing pages (item catalog, responses, account/settings, admin dashboards), server-side data fetching and mutation via trpc, user authentication via NextAuth with Discord OAuth, relational storage in PostgreSQL via Prisma ORM, and object storage in MinIO.

##### File structure
- Top-level config: next.config.js, tsconfig.json, tailwind.config.js, postcss.config.js, .eslintrc.json
- Public assets: public/robots.txt, public/site.webmanifest
- Localization: locales/en.json, locales/fr.json
- Database schema & migrations: prisma/schema.prisma + prisma/migrations/*
- Frontend React components under src/components (layout, ui, forms, lists)
- Pages conforming to Next.js conventions under src/pages (UI routes, API routes under pages/api and trpc)
- Custom hooks (src/hooks), utilities (src/utils), types (src/types), global styles (src/styles)
- Server logic under src/server: context, trpc setup, routers (item, response, user, patch‐version), db client, storage client

##### README for additional insights
- Uses PostgreSQL, MinIO, Discord OAuth, Node/npm
- Prisma migrations initialize and evolve the database
- NextAuth configuration for URL/secret, DISCORD_ID/SECRET
- Runs as a Next.js development server

a. Main components
- Browser/Client (UI)
- Next.js Web Server
- trpc API layer (in-process routers)
- Authentication Provider (Discord OAuth)
- PostgreSQL Database (Prisma ORM)
- Object Storage (MinIO)
- CDN or Static Assets (public folder + site.webmanifest)
b. Relationships & data flows
- User ↔ Browser: UI interactions, locale switching, form submissions
- Browser → Next.js Web Server: HTTP GET (SSR/SSG) and POST (API/trpc)
- Next.js Web Server ↔ trpc Router: in-process function calls via /api/trpc endpoint
- trpc Router ↔ Prisma Client → PostgreSQL: queries/mutations for items, responses, users, patch-versions, categories
- trpc Router ↔ MinIO Client: upload/download image blobs
- NextAuth (in Next.js API) ↔ Discord OAuth endpoints: token exchange, user profile retrieval
- Next.js Web Server → Browser: Serve React pages, serialized data from getServerSideProps or trpc hydration
c. Architectural patterns & principles
- Monorepo/workspace: frontend and backend code co-located under src
- API-centric design: trpc as typed RPC layer replacing REST
- MVC-style separation in routers (controllers), Prisma (model), React pages/components (view)
- Modular UI: reusable components (ui/, layouts/) and hooks
- Environment configuration for secrets/URLs in .env.local
d. Key technologies
- Next.js (SSR/SSG, API routes)
- React with TypeScript
- trpc (type-safe API layer)
- NextAuth.js (OAuth authentication)
- Prisma ORM + PostgreSQL
- MinIO (S3-compatible object storage)
- Tailwind CSS (styling)

##### Detail without over-fragmentation
- Every external dependency (Postgres, MinIO, Discord).
- Core in-process modules only at the layer level (do not list every .tsx file).
- Boundaries: Authentication, Data Access, Business Logic, Presentation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser/Client UI Layer
    subgraph "Browser/Client UI" 
        direction TB
        UIComp["Components<br/>(src/components)"]:::frontend
        PageIndex["Home Page<br/>(src/pages/index.tsx)"]:::frontend
        PageAccount["Account Page<br/>(src/pages/account/index.tsx)"]:::frontend
        PageAdmin["Admin Items<br/>(src/pages/admin/items.tsx)"]:::frontend
        PageItem["Item Detail<br/>(src/pages/item/[id].tsx)"]:::frontend
        PageAuthErr["Auth Error<br/>(src/pages/auth-error.tsx)"]:::frontend
    end

    %% Static Assets & Localization
    subgraph "Static Assets & Localization"
        direction TB
        Public["Public Assets<br/>(public/)"]:::frontend
        Robots["robots.txt"]:::frontend
        Manifest["site.webmanifest"]:::frontend
        Locales["Localization<br/>(locales/)"]:::frontend
    end

    %% Next.js Web Server
    subgraph "Next.js Web Server"
        direction TB
        NextServer["Next.js Server<br/>(entrypoint & config)"]:::backend
        AppShell["App Shell<br/>(src/pages/_app.tsx)"]:::backend
        Document["Document<br/>(src/pages/_document.tsx)"]:::backend
        NextServer --> AppShell
        NextServer --> Document
    end

    %% API Layer (trpc & NextAuth)
    subgraph "API Layer"
        direction TB
        TRPCEndpoint["trpc Endpoint<br/>(src/pages/api/trpc/[trpc].ts)"]:::backend
        TRPCSetup["trpc Setup<br/>(src/server/trpc.ts)"]:::backend
        TRPCRouters["Routers<br/>(src/server/routers/…)"]:::backend
        NextAuthRoute["NextAuth API<br/>(src/pages/api/auth/[...nextauth].ts)"]:::backend
        Context["Context & Session<br/>(src/server/context.ts)"]:::backend
        TRPCEndpoint --> TRPCSetup
        TRPCSetup --> TRPCRouters
        NextAuthRoute --> Context
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        PostgreSQL["PostgreSQL"]:::datastore
        PrismaClient["Prisma Client<br/>(src/server/db/client.ts)"]:::datastore
        Schema["Schema & Migrations<br/>(prisma/schema.prisma)"]:::datastore
        MinIOClient["MinIO Client<br/>(src/lib/minio.ts)"]:::datastore
        StorageSrv["Storage Service<br/>(src/server/storage.ts)"]:::datastore
        TRPCRouters --> PrismaClient
        PrismaClient --> PostgreSQL
        TRPCRouters --> StorageSrv
        StorageSrv --> MinIOClient
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Discord["Discord OAuth"]:::external
    end

    %% Connections
    PageIndex -->|HTTP| NextServer
    PageAccount -->|HTTP| NextServer
    PageAdmin -->|HTTP| NextServer
    PageItem -->|HTTP| NextServer
    PageAuthErr -->|HTTP| NextServer
    NextServer -->|RPC/API| TRPCEndpoint
    NextServer -->|Auth Calls| NextAuthRoute
    NextAuthRoute -- Token/Profile --> Discord
    Discord -- Callback --> NextAuthRoute
    NextServer -->|Serves| Public
    NextServer -->|Loads| Locales

    %% Click Events
    click UIComp "https://github.com/guillaumeca/circus-pes/tree/main/src/components"
    click PageIndex "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/index.tsx"
    click PageAccount "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/account/index.tsx"
    click PageAdmin "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/admin/items.tsx"
    click PageItem "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/item/[id].tsx"
    click PageAuthErr "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/auth-error.tsx"
    click Public "https://github.com/guillaumeca/circus-pes/tree/main/public"
    click Locales "https://github.com/guillaumeca/circus-pes/tree/main/locales"
    click AppShell "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/_app.tsx"
    click Document "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/_document.tsx"
    click TRPCEndpoint "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/api/trpc/[trpc].ts"
    click TRPCSetup "https://github.com/guillaumeca/circus-pes/blob/main/src/server/trpc.ts"
    click NextAuthRoute "https://github.com/guillaumeca/circus-pes/blob/main/src/pages/api/auth/[...nextauth].ts"
    click Context "https://github.com/guillaumeca/circus-pes/blob/main/src/server/context.ts"
    click PrismaClient "https://github.com/guillaumeca/circus-pes/blob/main/src/server/db/client.ts"
    click Schema "https://github.com/guillaumeca/circus-pes/blob/main/prisma/schema.prisma"
    click MinIOClient "https://github.com/guillaumeca/circus-pes/blob/main/src/lib/minio.ts"
    click StorageSrv "https://github.com/guillaumeca/circus-pes/blob/main/src/server/storage.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
