# juosorioca420/chizu-project architecture

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

- Interactive diagram: https://gitdiagram.com/juosorioca420/chizu-project
- Repository: https://github.com/juosorioca420/chizu-project

## Overview

##### Project type and purpose
- Project type: Full-stack web application
- Purpose: “Chizu” is a marketplace and crowdfunding platform for indie video games. Players can browse, purchase, download, and review games. Developers can create subscription‐based funding campaigns with tiered rewards.

##### High-level file structure & key indicators
- src/app: Next.js 13 “app” directory with React Server & Client Components, dynamic routes, API folder.
- src/pages/api & src/app/api/trpc: Two API surfaces—traditional Next.js API Routes and a tRPC router.
- server.ts, payload.config.ts, payload-types.ts: A Payload CMS instance running in a custom Node/Express server.
- firebaseConfig.ts & src/LOGIN: Google/Firebase authentication layer (used in a legacy login module).
- lib/stripe.ts & webhooks.ts: Stripe payment integration and webhook handlers.
- collections & payload-types: MongoDB data models managed by Payload CMS.

##### README insights
- Auth via Google
- Payments through Stripe
- Downloadable digital assets
- Library, cart, campaigns, subscriptions
- Responsive design, fast response, PCI-DSS compliance

##### Main components
a. Frontend (Client Browser)
- React (Next.js 13) Server & Client Components
- Pages: storefront, campaigns, cart, library, auth flows
- Static assets served from /public (logos, images, ZIPs)
b. Authentication Service
- Firebase Authentication (Google OAuth)
- Custom session store (if any) in Payload or Next.js
c. API Layer
- Next.js API Routes (/pages/api) for REST-style endpoints (e.g., email-receipt, payment-status)
- tRPC router (/src/app/api/trpc & /src/trpc) for type-safe RPC calls
d. CMS & Business Logic Server
- Payload CMS (runs in server.ts) managing MongoDB collections
- Business code in trpc routers (auth-router.tsx, payment-router.ts)
e. Database
- MongoDB (collections defined in /collections)
f. External Services
- Stripe (charges, subscriptions, webhooks)
- Email Service (SMTP or third-party for receipts)
- (Optional) Google Lighthouse / Analytics

##### Relationships & interactions
- User → Browser (UI components)
- Browser → Next.js Server (SSR, API calls)
- Next.js Frontend →
- tRPC client → tRPC server → Payload CMS → MongoDB
- REST API → Next.js API Routes → payload-utils / lib → MongoDB or external
- Firebase Auth SDK → Firebase Auth → JWT/session
- Stripe SDK → Stripe API → webhooks → Next.js Server or Payload CMS
- Payload CMS Admin UI (for developers) → Payload Server → MongoDB

##### Architectural patterns & design principles
- React Server Components (Next.js “app” directory) for performance and SEO
- API-first design with a hybrid of REST (Next.js API Routes) and RPC (tRPC)
- CMS as a self-contained microservice (Payload on Node/Express)
- Event-driven webhooks for payment notifications
- Separation of concerns: UI / Auth / API / Data persistence

##### Technologies & frameworks
- Frontend: Next.js 13, React, TypeScript, Tailwind CSS
- API: Next.js API Routes, tRPC, Node.js/Express
- CMS: Payload CMS
- Database: MongoDB
- Auth: Firebase Authentication (Google OAuth)
- Payments: Stripe
- Utilities: Zod validators, custom hooks, shared components

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Zone
  subgraph "Client (Browser)"
    direction TB
    Frontend["Next.js 13 Frontend"]:::ui
    StaticAssets["Static Assets"]:::ui
    FirebaseSDK["Firebase Auth SDK"]:::ui
    StripeSDK["Stripe SDK"]:::ui
  end

  %% Auth Legacy Module
  subgraph "Legacy Login Module" 
    direction TB
    FirebaseConfig["firebaseConfig.ts"]:::ui
    LoginApp["App.tsx"]:::ui
    AuthPages["LOGIN/pages"]:::ui
    AuthLib["auth.ts"]:::ui
  end

  %% Server Zone
  subgraph "Server (Next.js + Payload CMS)"
    direction TB

    subgraph "API Layer" 
      direction TB
      REST["Next.js API Routes"]:::api
      EmailReceipt["email-receipt.ts"]:::api
      PaymentStatus["payment-status.ts"]:::api
      GetCampaigns["get-campaigns.ts"]:::api
      GetLibrary["get-library.ts"]:::api
      Reviews["reviews.ts"]:::api

      tRPCEntry["/app/api/trpc/[trpc]/route.tsx"]:::api
      AuthRouter["auth-router.tsx"]:::api
      PaymentRouter["payment-router.ts"]:::api
      TRPCIndex["index.ts"]:::api
      TRPCT["trpc.ts"]:::api
    end

    subgraph "CMS & Business Logic" 
      direction TB
      PayloadServer["server.ts"]:::biz
      PayloadConfig["payload.config.ts"]:::biz
      PayloadTypes["payload-types.ts"]:::biz
      PayloadUtils["payload-utils.ts"]:::biz
    end

    subgraph "Stripe Integration"
      direction TB
      StripeClient["stripe.ts"]:::biz
      WebhookHandler["webhooks.ts"]:::biz
    end

    subgraph "Email Service"
      direction TB
      EmailTemplate["Receipt.tsx"]:::biz
    end

    subgraph "Utilities & Config"
      direction TB
      Utils["utils.ts"]:::biz
      Validators["validators.ts"]:::biz
      NextConfig["next.config.mjs"]:::biz
      TailwindConfig["tailwind.config.ts"]:::biz
      EnvExample[".env.example"]:::biz
      Middleware["middleware.ts"]:::biz
    end

    subgraph "Database"
      direction TB
      MongoDB["MongoDB"]:::db
      Collections["src/collections"]:::db
      Campaigns["Campaigns"]:::db
      Products["Products"]:::db
      Users["Users.ts"]:::db
    end
  end

  %% External Services
  subgraph "External Services"
    direction TB
    FirebaseAuth["Firebase Authentication"]:::ext
    StripeAPI["Stripe API"]:::ext
    EmailProvider["Email Service (SMTP)"]:::ext
  end

  %% Connections
  Frontend -->|"REST over HTTPS"| REST
  Frontend -->|"tRPC over HTTP"| tRPCEntry
  Frontend -->|"Firebase OAuth"| FirebaseSDK
  Frontend -->|"Stripe Checkout"| StripeSDK
  Frontend -->|"Static Assets"| StaticAssets

  FirebaseSDK -->|"OAuth flow"| FirebaseAuth

  REST -->|calls| EmailReceipt
  REST -->|calls| PaymentStatus
  REST -->|calls| GetCampaigns
  REST -->|calls| GetLibrary
  REST -->|calls| Reviews
  REST -->|"access"| PayloadServer

  tRPCEntry -->|routes to| AuthRouter
  tRPCEntry -->|routes to| PaymentRouter
  tRPCEntry -->|routes to| TRPCIndex
  tRPCEntry -->|uses| TRPCT
  tRPCEntry -->|"access"| PayloadServer

  PayloadServer -->|"reads/writes"| MongoDB
  PayloadServer -->|"uses models"| Collections
  Collections --> Campaigns
  Collections --> Products
  Collections --> Users

  StripeSDK -->|"calls"| StripeAPI
  StripeAPI -.->|"webhook"| WebhookHandler
  WebhookHandler -->|process| PayloadServer

  EmailReceipt -->|"sends via"| EmailProvider
  EmailTemplate -->|"render"| EmailProvider

  %% Legacy Login Module connections
  Frontend --> FirebaseConfig
  Frontend --> LoginApp
  Frontend --> AuthPages
  Frontend --> AuthLib

  %% Click Events
  click Frontend "https://github.com/juosorioca420/chizu-project/tree/main/src/app"
  click StaticAssets "https://github.com/juosorioca420/chizu-project/tree/main/public/"
  click StaticAssets "https://github.com/juosorioca420/chizu-project/tree/main/src/product_files/"
  click FirebaseConfig "https://github.com/juosorioca420/chizu-project/blob/main/src/LOGIN/firebaseConfig.ts"
  click LoginApp "https://github.com/juosorioca420/chizu-project/blob/main/src/LOGIN/App.tsx"
  click AuthPages "https://github.com/juosorioca420/chizu-project/tree/main/src/LOGIN/pages"
  click AuthLib "https://github.com/juosorioca420/chizu-project/blob/main/src/lib/auth.ts"
  click REST "https://github.com/juosorioca420/chizu-project/tree/main/src/pages/api"
  click EmailReceipt "https://github.com/juosorioca420/chizu-project/blob/main/src/pages/api/email-receipt.ts"
  click PaymentStatus "https://github.com/juosorioca420/chizu-project/blob/main/src/pages/api/payment-status.ts"
  click GetCampaigns "https://github.com/juosorioca420/chizu-project/blob/main/src/pages/api/get-campaigns.ts"
  click GetLibrary "https://github.com/juosorioca420/chizu-project/blob/main/src/pages/api/get-library.ts"
  click Reviews "https://github.com/juosorioca420/chizu-project/blob/main/src/pages/api/reviews.ts"
  click tRPCEntry "https://github.com/juosorioca420/chizu-project/blob/main/src/app/api/trpc/[trpc]/route.tsx"
  click AuthRouter "https://github.com/juosorioca420/chizu-project/blob/main/src/trpc/auth-router.tsx"
  click PaymentRouter "https://github.com/juosorioca420/chizu-project/blob/main/src/trpc/payment-router.ts"
  click TRPCIndex "https://github.com/juosorioca420/chizu-project/blob/main/src/trpc/index.ts"
  click TRPCT "https://github.com/juosorioca420/chizu-project/blob/main/src/trpc/trpc.ts"
  click PayloadServer "https://github.com/juosorioca420/chizu-project/blob/main/src/server.ts"
  click PayloadConfig "https://github.com/juosorioca420/chizu-project/blob/main/src/payload.config.ts"
  click PayloadTypes "https://github.com/juosorioca420/chizu-project/blob/main/src/payload-types.ts"
  click PayloadUtils "https://github.com/juosorioca420/chizu-project/blob/main/src/lib/payload-utils.ts"
  click StripeClient "https://github.com/juosorioca420/chizu-project/blob/main/src/lib/stripe.ts"
  click WebhookHandler "https://github.com/juosorioca420/chizu-project/blob/main/src/webhooks.ts"
  click EmailTemplate "https://github.com/juosorioca420/chizu-project/blob/main/src/components/email/Receipt.tsx"
  click Utils "https://github.com/juosorioca420/chizu-project/blob/main/src/lib/utils.ts"
  click Validators "https://github.com/juosorioca420/chizu-project/blob/main/src/lib/validators.ts"
  click NextConfig "https://github.com/juosorioca420/chizu-project/blob/main/next.config.mjs"
  click TailwindConfig "https://github.com/juosorioca420/chizu-project/blob/main/tailwind.config.ts"
  click EnvExample "https://github.com/juosorioca420/chizu-project/blob/main/.env.example"
  click Middleware "https://github.com/juosorioca420/chizu-project/blob/main/src/middleware.ts"
  click Collections "https://github.com/juosorioca420/chizu-project/tree/main/src/collections"
  click Campaigns "https://github.com/juosorioca420/chizu-project/tree/main/src/collections/Campaigns"
  click Products "https://github.com/juosorioca420/chizu-project/tree/main/src/collections/Products"
  click Users "https://github.com/juosorioca420/chizu-project/blob/main/src/collections/Users.ts"

  %% Styles
  classDef ui fill:#E0F7FA,stroke:#006064,color:#006064
  classDef api fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
  classDef biz fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
  classDef db fill:#ECEFF1,stroke:#607D8B,color:#37474F
  classDef ext fill:#FFEBEE,stroke:#C62828,color:#C62828
```
