How guillaumeca/circus-pes works
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.