How ronakmaheshwari/capital works
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.