# ronakmaheshwari/capital architecture

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

- Interactive diagram: https://gitdiagram.com/ronakmaheshwari/capital
- Repository: https://github.com/ronakmaheshwari/capital

## Overview

##### Project Type and Purpose
- Capital is a **full-stack, microservices-style event ticketing platform** with a Next.js web frontend and multiple TypeScript/Node.js backend services.
- Its goal is secure, fraud-resistant ticket issuance, real-time validation, refund management, and internal wallet/payout orchestration.

##### File Structure
- **Monorepo Layout** using Turbo:
- /apps: four primary services—`http` (REST API + workers), `validator` (ticket scanning/validation), `webhook` (payment reconciliation), `web` (Next.js UI).
- /packages: shared libraries—`db` (Prisma + PostgreSQL schema), `cache` (Redis wrapper), `notifications` (email/OTP), `keygen` (crypto utilities), `types` (TS types), `ui` & lint/config packages.
- /docker & docker-compose files: container build contexts for each service.
- /prometheus.yml, GitHub workflows: observability and CI/CD.

##### README for Additional Insights
- **Architecture Highlights**:
- Centralized backend (PostgreSQL + Redis) as source of truth.
- Decentralized crypto (Ed25519) for signed tickets.
- Three-queue mechanism (Pending, In-Progress, Dead-Letter) via Redis Queue.
- Validators (mobile/kiosk) connect via WebSocket or REST to the `validator` service.
- **Tech Stack**: Node.js, Express, Prisma, Redis, WebSocket, Next.js, React, Tailwind, Shadcn/UI, GitOps, Kubernetes, Prometheus, Grafana.

a. Main Components
1. **Web Frontend**
- Next.js app (`/apps/web`)
- Consumes REST APIs & WebSocket for real‐time updates
2. **API Gateway / HTTP Service**
- Express (`/apps/http`)
- Issue tickets, user/auth flows, event listing, schedule jobs
3. **Validator Service**
- Express + WebSocket (`/apps/validator`)
- Real-time ticket signature & ownership verification
4. **Webhook Processor**
- Express (`/apps/webhook`)
- Handles payment provider webhooks, triggers state changes
5. **Background Workers**
- Shared by `/apps/http`, `/apps/validator`, `/apps/webhook`
- Listen on Redis queues (pending → in-progress → dead-letter)
6. **Data Stores & Caches**
- PostgreSQL via Prisma (`/packages/db`)
- Redis (caching, queues, pub/sub) (`/packages/cache`)
7. **Shared Libraries / Services**
- Notifications (`/packages/notifications`), Keygen (`/packages/keygen`), Types, UI components
8. **External Integrations**
- Resend (email), Supabase (storage), Prometheus & Grafana (metrics), Nginx (ingress), Docker/K8s

b. Relationships & Data Flow
- User’s browser ↔ Next.js (HTTPS) ↔ HTTP API
- HTTP API ↔ PostgreSQL (Prisma queries) & Redis (cache reads/writes, queue publishes)
- HTTP API publishes ticket jobs → Redis Pending Queue → Worker → validation jobs → Validator Service
- Validator Service ↔ Redis Pub/Sub to broadcast validation results
- Webhook Service listens to external payment provider → updates DB/queues → triggers notifications
- Background Workers consume queues → call Notifications & Keygen libs → update DB
- Prometheus scrapes metrics endpoints from each service → Grafana dashboards

c. Architectural Patterns & Principles
- **Microservices & Modular Monorepo**: clear `/apps` per bounded context, `/packages` for shareable code.
- **Event-Driven**: Redis queues & pub/sub decouple services and scale horizontally.
- **Hexagonal/Onion**: business logic in libs (`keygen`, `notifications`), adapters in `/apps/*`.
- **Centralized State + Decentralized Trust**: DB/Redis authoritative + Ed25519 ticket signing.
- **Containerized & Cloud-Native**: Dockerfiles per service, orchestrated via Docker Compose or Kubernetes.

d. Key Technologies to Call Out
- Node.js + Express
- Prisma + PostgreSQL
- Redis (cache, queue, pub/sub)
- Ed25519 crypto (Keygen package)
- Next.js (React + Shadcn/UI + Tailwind)
- Docker, Kubernetes, GitHub Actions
- Prometheus & Grafana for metrics

##### Detail
- Break out sub-components within services if needed (e.g., “TicketController”, “ScheduleWorker”).
- **three-queue mechanism** explicitly.
- How **cryptographic signing** occurs in the HTTP API (Keygen lib) and verification in Validator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Web["Web Frontend\nNext.js"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        HTTP["HTTP Service\nExpress (apps/http)"]:::api
        Validator["Validator Service\nExpress + WebSocket (apps/validator)"]:::api
        Webhook["Webhook Processor\nExpress (apps/webhook)"]:::api
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        WorkerHTTP["HTTP Worker\napps/http/src/workers/worker.ts"]:::api
        WorkerValidator["Validator Worker\napps/validator/src/workers/worker.ts"]:::api
        WorkerWebhook["Webhook Worker\napps/webhook/src/workers/worker.ts"]:::api
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        Schema["Prisma Schema\npackages/db/prisma/schema.prisma"]:::data
        DBlib["Prisma Client Lib\npackages/db/src/index.ts"]:::data
        CacheLib["Redis Cache/Queue Lib\npackages/cache/src/index.ts"]:::data
        NotificationsLib["Notifications Lib\npackages/notifications/src/index.ts"]:::api
        EmailSrv["Email Service\npackages/notifications/src/services/emailService.ts"]:::api
        OTPUtil["OTP Generator\npackages/notifications/src/utils/otpGenerator.ts"]:::api
        KeygenLib["Keygen (Ed25519)\npackages/keygen/src/index.ts"]:::api
        TypesLib["Types\npackages/types/src/index.ts"]:::data
        UILib["UI Components\npackages/ui/src"]:::ui
        SwaggerHTTP["HTTP Swagger\nswagger/http_spec.yaml"]:::infra
        SwaggerVal["Validator Swagger\nswagger/validator_spec.yaml"]:::infra
        SwaggerHook["Webhook Swagger\nswagger/webhook_spec.yaml"]:::infra
    end

    %% Data Stores & Cache
    subgraph "Data Stores & Cache"
        direction TB
        Postgres["PostgreSQL"]:::data
        Redis["Redis\nQueues & Pub/Sub"]:::data
    end

    %% External Integrations
    subgraph "External Systems"
        direction TB
        Resend["Resend Email"]:::external
        Supabase["Supabase Storage"]:::external
        PaymentProvider["Payment Provider\nWebhooks"]:::external
    end

    %% Monitoring & Infra
    subgraph "Monitoring & Infra"
        direction TB
        Prometheus["Prometheus\nprometheus.yml"]:::infra
        Grafana["Grafana Dashboards"]:::infra
        Nginx["Nginx Ingress"]:::infra
        DockerFiles["Docker Build Contexts\n(docker/*.http,..)"]:::infra
        DockerCompose["Docker Compose Configs"]:::infra
        CICD["CI/CD Workflows\n.github/workflows"]:::infra
    end

    %% Metrics Endpoints
    METRICH["/metrics\napps/http/src/metrics/requestCount.ts"]:::infra
    METRICV["/metrics\napps/validator/src/metrics/requestCount.ts"]:::infra
    METRICHK["/metrics\napps/webhook/src/metrics/requestCount.ts"]:::infra

    %% Connections
    Web -->|"HTTPS"| HTTP
    Web -->|"WebSocket"| Validator

    HTTP -->|"Prisma Queries"| Postgres
    HTTP -->|"Cache & Queue"| Redis
    HTTP -->|"/metrics"| METRICH

    Validator -->|"Redis Pub/Sub"| Redis
    Validator -->|"/metrics"| METRICV

    Webhook -->|"Prisma Queries"| Postgres
    Webhook -->|"Cache & Queue"| Redis
    Webhook -->|"/metrics"| METRICHK

    HTTP -->|"Publish Ticket Job"| WorkerHTTP
    WorkerHTTP -->|"Process & Sign"| KeygenLib
    WorkerHTTP -->|"Store Ticket"| DBlib
    WorkerHTTP -->|"Notify"| NotificationsLib

    Validator -->|"Publish Validation Job"| WorkerValidator
    WorkerValidator -->|"Verify Signature"| KeygenLib
    WorkerValidator -->|"Update Status"| DBlib
    WorkerValidator -->|"Notifications"| NotificationsLib

    Webhook -->|"Publish Payment Job"| WorkerWebhook
    WorkerWebhook -->|"Process Webhook"| DBlib
    WorkerWebhook -->|"Notify User"| NotificationsLib

    NotificationsLib --> EmailSrv
    NotificationsLib --> OTPUtil

    HTTP --> DBlib
    Validator --> DBlib
    Webhook --> DBlib

    HTTP --> CacheLib
    Validator --> CacheLib
    Webhook --> CacheLib

    HTTP --> TypesLib
    Validator --> TypesLib
    Webhook --> TypesLib
    Web --> UILib

    HTTP --> SwaggerHTTP
    Validator --> SwaggerVal
    Webhook --> SwaggerHook

    Postgres --> DBlib
    Redis --> CacheLib

    Prometheus --> HTTP
    Prometheus --> Validator
    Prometheus --> Webhook
    Grafana --> Prometheus

    PaymentProvider --> Webhook
    Resend --> NotificationsLib
    Supabase --> Web

    Nginx --> HTTP
    Nginx --> Validator
    Nginx --> Webhook
    DockerCompose --> DockerFiles
    CICD --> DockerFiles
    CICD --> DockerCompose

    %% Click Events
    click Web "https://github.com/ronakmaheshwari/capital/tree/main/apps/web"
    click HTTP "https://github.com/ronakmaheshwari/capital/tree/main/apps/http"
    click Validator "https://github.com/ronakmaheshwari/capital/tree/main/apps/validator"
    click Webhook "https://github.com/ronakmaheshwari/capital/tree/main/apps/webhook"
    click WorkerHTTP "https://github.com/ronakmaheshwari/capital/blob/main/apps/http/src/workers/worker.ts"
    click WorkerValidator "https://github.com/ronakmaheshwari/capital/blob/main/apps/validator/src/workers/worker.ts"
    click WorkerWebhook "https://github.com/ronakmaheshwari/capital/blob/main/apps/webhook/src/workers/worker.ts"
    click Schema "https://github.com/ronakmaheshwari/capital/blob/main/packages/db/prisma/schema.prisma"
    click DBlib "https://github.com/ronakmaheshwari/capital/blob/main/packages/db/src/index.ts"
    click CacheLib "https://github.com/ronakmaheshwari/capital/blob/main/packages/cache/src/index.ts"
    click NotificationsLib "https://github.com/ronakmaheshwari/capital/blob/main/packages/notifications/src/index.ts"
    click EmailSrv "https://github.com/ronakmaheshwari/capital/blob/main/packages/notifications/src/services/emailService.ts"
    click OTPUtil "https://github.com/ronakmaheshwari/capital/blob/main/packages/notifications/src/utils/otpGenerator.ts"
    click KeygenLib "https://github.com/ronakmaheshwari/capital/blob/main/packages/keygen/src/index.ts"
    click TypesLib "https://github.com/ronakmaheshwari/capital/blob/main/packages/types/src/index.ts"
    click UILib "https://github.com/ronakmaheshwari/capital/tree/main/packages/ui/src"
    click SwaggerHTTP "https://github.com/ronakmaheshwari/capital/blob/main/swagger/http_spec.yaml"
    click SwaggerVal "https://github.com/ronakmaheshwari/capital/blob/main/swagger/validator_spec.yaml"
    click SwaggerHook "https://github.com/ronakmaheshwari/capital/blob/main/swagger/webhook_spec.yaml"
    click METRICH "https://github.com/ronakmaheshwari/capital/blob/main/apps/http/src/metrics/requestCount.ts"
    click METRICV "https://github.com/ronakmaheshwari/capital/blob/main/apps/validator/src/metrics/requestCount.ts"
    click METRICHK "https://github.com/ronakmaheshwari/capital/blob/main/apps/webhook/src/metrics/requestCount.ts"
    click DockerFiles "https://github.com/ronakmaheshwari/capital/tree/main/docker"
    click DockerCompose "https://github.com/ronakmaheshwari/capital/blob/main/docker-compose.yml"
    click CICD "https://github.com/ronakmaheshwari/capital/blob/main/.github/workflows/build.yml"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#0366d6,color:#000
    classDef api fill:#d9ead3,stroke:#274e13,color:#000
    classDef data fill:#f4cccc,stroke:#a61c00,color:#000
    classDef infra fill:#fff2cc,stroke:#7f6000,color:#000
    classDef external fill:#ead1dc,stroke:#660033,color:#000
```
