# harshit27gupta/events architecture

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

- Interactive diagram: https://gitdiagram.com/harshit27gupta/events
- Repository: https://github.com/harshit27gupta/events

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-based events and ticketing platform.
- Frontend: React app in apps/web.
- Backend: multiple Node/Express TypeScript services (gateway, auth, events, orders) and a FastAPI ML service.
- Shared code: packages/common for logging, config, Mongo/Redis clients.
- Supporting infra: MongoDB (one DB per service), Redis, RabbitMQ.

##### Main Components
- Web UI (apps/web): React SPA served via Docker.
- API Gateway (services/gateway): Express BFF handling CORS, cookies → Authorization, rate limiting, circuit breaker.
- Auth Service (services/auth): signup/login/logout/refresh, session storage in Redis, JWT generation/verification.
- Events Service (services/events): CRUD operations with RBAC, payload validation, organizer ownership.
- Orders Service (services/orders): seat holds in Redis (TTL), idempotent purchase, Mongo transactions, simulated payments.
- ML Service (services/ml-service): FastAPI recommendation endpoints.
- Shared Library (packages/common): singleton clients (Mongo, Redis), config, logger, middleware.
- Datastores:
- MongoDB – separate database instance per service (users, events, orders)
- Redis – holds, idempotency cache, refresh tokens, payment intents
- RabbitMQ – message broker (for future domain events)

##### Relationships and Data Flow
- Browser ←→ Web UI (static assets + JS)
- Web UI –HTTP(cookies)→ API Gateway (port 8080)
- API Gateway routes:
- /api/auth/* → Auth Service
- /api/events/* → Events Service
- /api/orders/* → Orders Service
- Gateway uses in-process HTTP clients (packages/common/api.ts) and applies circuit breaker.
- Auth & Orders services read/write to Redis for tokens, holds, idempotency.
- Each service uses its own MongoDB for persistence.
- Orders service also writes to Mongo inside multi-document transaction when confirming purchase.
- ML Service (port 5000) can be called directly from UI or proxied via Gateway.
- RabbitMQ sits off-to-the-side for domain events (not yet in main flow).

##### Architectural Patterns & Design Principles
- BFF (Backend-for-Frontend) pattern in Gateway.
- Circuit Breaker (opossum) at gateway → Events/Orders calls.
- Singleton pattern in shared clients.
- Repository pattern for DB access in each service.
- Idempotency key pattern in Orders (safe retries).
- TTL-based seat hold pattern in Redis.
- Transactional writes with Mongo session.
- Zod schema validation for payloads.

##### Essential Elements to Capture
- Notes on patterns: circuit breaker at gateway, idempotency in orders, transactional writes.
- Shared code in a single block and show each service importing from it.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Browser"]:::frontend
        WebUI["Web UI (React SPA)"]:::frontend
    end

    Browser -->|"HTTP (JS assets)"| WebUI
    WebUI -->|"HTTP (cookies)\nGET/POST"| Gateway

    %% Backend Layer
    subgraph "Backend Layer"
        Gateway["API Gateway<br/>(Express BFF)"]:::gateway

        subgraph "Microservices"
            Auth["Auth Service"]:::service
            Events["Events Service"]:::service
            Orders["Orders Service"]:::service
            ML["ML Service<br/>(FastAPI)"]:::service
        end

        Common["packages/common"]:::common
    end

    Gateway -->|"POST/GET /api/auth/*"| Auth
    Gateway -->|"POST/GET /api/events/*"| Events
    Gateway -->|"POST/GET /api/orders/*"| Orders
    Gateway -.->|"optional proxy\n(port 5000)"| ML

    Auth --> Common
    Events --> Common
    Orders --> Common
    Gateway --> Common
    ML --> Common

    %% Datastores
    subgraph "Data Stores"
        MongoAuth[(MongoDB<br/>Auth)]:::db
        MongoEvents[(MongoDB<br/>Events)]:::db
        MongoOrders[(MongoDB<br/>Orders)]:::db
        Redis[(Redis)]:::redis
        Rabbit[(RabbitMQ)]:::broker
    end

    Auth -->|"users data"| MongoAuth
    Events -->|"events data"| MongoEvents
    Orders -->|"purchase:transaction"| MongoOrders

    Auth -->|"session tokens"| Redis
    Orders -->|"holds:set (TTL)"| Redis
    Orders -->|"idempotency keys"| Redis

    Events -.->|"domain events"| Rabbit
    Orders -.->|"domain events"| Rabbit

    %% Click Events
    click WebUI "https://github.com/harshit27gupta/events/tree/main/apps/web"
    click Gateway "https://github.com/harshit27gupta/events/blob/main/services/gateway/src/index.ts"
    click Auth "https://github.com/harshit27gupta/events/blob/main/services/auth/src/index.ts"
    click Events "https://github.com/harshit27gupta/events/blob/main/services/events/src/index.ts"
    click Orders "https://github.com/harshit27gupta/events/blob/main/services/orders/src/index.ts"
    click ML "https://github.com/harshit27gupta/events/blob/main/services/ml-service/app/main.py"
    click Common "https://github.com/harshit27gupta/events/blob/main/packages/common/src/index.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef gateway fill:#FFA500,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef common fill:#DCDCDC,stroke:#000,stroke-width:1px
    classDef db fill:#DA70D6,stroke:#000,stroke-width:1px
    classDef redis fill:#FF6347,stroke:#000,stroke-width:1px
    classDef broker fill:#D3D3D3,stroke:#000,stroke-width:1px
```
