# drezzgo/oneticket-sistema-distribuido-docker architecture

> Architecture diagram of the GitHub repository drezzgo/oneticket-sistema-distribuido-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drezzgo/oneticket-sistema-distribuido-docker
- Repository: https://github.com/drezzgo/oneticket-sistema-distribuido-docker

## Overview

1. **System shape**
   - OneTicket is a Dockerized distributed reservation system with four runtime tiers: browser frontend, Nginx reverse proxy, two interchangeable Node.js backends, and a single PostgreSQL database.
   - The main architectural boundary is that the frontend never talks to PostgreSQL directly; all application traffic goes through Nginx and one of the backends.

2. **Frontend subsystem**
   - `frontend/` is an Astro app with a React dashboard component in `src/components/Dashboard.tsx`.
   - Its role is operator-facing control and observability: it polls the API for event/health state, triggers reservation/load/failover tests, and presents the system status visually.
   - The frontend is served separately on `localhost:4321`, while API calls are made through the Nginx entrypoint on `localhost`.

3. **Edge and routing layer**
   - `nginx/` is the single public API ingress on port 80.
   - `nginx/nginx.conf` defines an upstream cluster pointing to `backend-a` and `backend-b`, so requests are load-balanced between the two backend containers.
   - This layer also provides failover behavior when one backend is unavailable, keeping the browser-facing URL stable.

4. **Backend replication model**
   - `backend-a/` and `backend-b/` are structurally identical services, each with its own Docker image and the same source layout.
   - This duplication is intentional: the architecture is active-active at the application layer, with both nodes able to serve the same routes and share the same database.
   - The distinction between A and B is primarily operational, not functional.

5. **Backend application boundaries**
   - Each backend is a Node.js/TypeScript service with an HTTP server entrypoint in `src/index.ts`.
   - Route modules are split by concern: `routes/health.ts`, `routes/eventos.ts`, `routes/reserva.ts`, `routes/admin.ts`, and `routes/autoscale.ts`.
   - This makes the backend a small API gateway plus reservation worker rather than a monolith with UI concerns.

6. **Reservation and concurrency path**
   - The critical business flow is `POST /reserva` in `routes/reserva.ts`.
   - That route uses PostgreSQL transactions and row locking semantics to prevent double-booking when both backend replicas receive competing requests.
   - This is the main data-integrity boundary in the system: concurrency is resolved in the database, not in-memory.

7. **Shared state and simulation hooks**
   - Each backend has a `state.ts` file used for local node state such as simulated delays or node health toggles.
   - `routes/autoscale.ts` exposes controls that let the frontend induce latency/load conditions for demonstrations.
   - `routes/admin.ts` provides operational controls such as node toggling and reset behavior, which are useful for failover and recovery testing.

8. **Database subsystem**
   - `database/init.sql` initializes PostgreSQL with the reservation domain schema, including ticket/event availability and a virtual queue.
   - PostgreSQL is the system of record for ticket inventory and reservation outcomes.
   - The database is not just persistence; it is also the coordination point for contention control across replicas.

9. **Data flow: normal reservation**
   - Browser action in the dashboard triggers an HTTP request to Nginx.
   - Nginx forwards the request to one backend replica.
   - That backend opens a PostgreSQL transaction, checks/updates the relevant ticket state, and returns success or a conflict response.
   - The response travels back through Nginx to the frontend for display.

10. **Data flow: distributed tests and admin actions**
   - The dashboard can generate concurrent reservations, simulated overload, and node toggles to exercise the distributed behavior.
   - These actions primarily hit the `/admin/*` and `/autoscale/*` endpoints, which change node behavior rather than business data.
   - This separates operational simulation from the core reservation path.

11. **Virtual queue/work-processor behavior**
   - The README describes a queue-based workflow for burst handling, and the code layout reflects that with `virtual_queue` in the schema and periodic processing in backend startup logic.
   - This is a second coordination mechanism beside direct reservations: instead of immediate ticket allocation, requests can be staged and drained in controlled batches.
   - For a diagram, treat this as an asynchronous path inside the backend/database boundary.

12. **Deployment topology**
   - `docker-compose.yml` defines the complete system as a multi-container deployment on a shared Docker network.
   - The key exposed ports are frontend on `4321`, Nginx on `80`, and PostgreSQL on `5432`.
   - Each service also has its own `Dockerfile`, so the repo is organized around containerized runtime images rather than a single build artifact.

13. **Operational constraints**
   - The system assumes the presence of a reachable PostgreSQL instance and a Docker network that all containers share.
   - Resets, health checks, and failover are part of the intended operating model, not just debug tooling.
   - The architecture is therefore optimized for demonstration of distributed-systems concepts: load balancing, failover, concurrency control, and queueing.

14. **What to draw in an architecture diagram**
   - Show a browser-facing frontend, an Nginx ingress/load balancer, two equal backend replicas, and a central PostgreSQL database.
   - Draw one synchronous request path for reservations and read-only status polling, and a separate admin/simulation path for toggling nodes and injecting latency.
   - Emphasize the database as the shared consistency boundary and the backends as stateless-ish replicas with local simulation state.

Main entry points: [`docker-compose.yml`](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/docker-compose.yml) (Compose), [`backend-a/src/routes/reserva.ts`](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/routes/reserva.ts) (A routes), [`backend-b/src/routes/reserva.ts`](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/routes/reserva.ts) (B routes), [`frontend/src/components/Dashboard.tsx`](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/src/components/Dashboard.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_ui(("Browser UI<br/>client<br/>[index.astro]"))
  node_dashboard["Dashboard<br/>react component<br/>[Dashboard.tsx]"]
  node_frontend_app["Astro app<br/>frontend app<br/>[package.json]"]
end

subgraph group_edge["Edge"]
  node_nginx_conf["Ingress<br/>nginx config<br/>[nginx.conf]"]
  node_nginx_image["Nginx image<br/>container image"]
end

subgraph group_backends["Backends"]
  node_backend_a_app["Backend A<br/>node service<br/>[index.ts]"]
  node_backend_a_routes["A routes<br/>api routes<br/>[reserva.ts]"]
  node_backend_a_state["A state<br/>runtime state<br/>[state.ts]"]
  node_backend_a_db["A db<br/>db access<br/>[db.ts]"]
  node_backend_b_app["Backend B<br/>node service<br/>[index.ts]"]
  node_backend_b_routes["B routes<br/>api routes<br/>[reserva.ts]"]
  node_backend_b_state["B state<br/>runtime state<br/>[state.ts]"]
  node_backend_b_db["B db<br/>db access<br/>[db.ts]"]
end

subgraph group_data["Data"]
  node_postgres[("PostgreSQL<br/>database<br/>[init.sql]")]
  node_schema["Schema<br/>init sql<br/>[init.sql]"]
end

subgraph group_deployment["Deployment"]
  node_compose["Compose<br/>deployment spec<br/>[docker-compose.yml]"]
  node_backend_a_img["A image<br/>container image"]
  node_backend_b_img["B image<br/>container image"]
end

node_browser_ui -->|"renders"| node_dashboard
node_dashboard -->|"API calls"| node_nginx_conf
node_frontend_app -->|"serves"| node_browser_ui
node_nginx_conf -->|"routes to"| node_backend_a_app
node_nginx_conf -->|"routes to"| node_backend_b_app
node_backend_a_app -->|"mounts"| node_backend_a_routes
node_backend_b_app -->|"mounts"| node_backend_b_routes
node_backend_a_routes -->|"reads/writes"| node_backend_a_db
node_backend_b_routes -->|"reads/writes"| node_backend_b_db
node_backend_a_routes -->|"uses"| node_backend_a_state
node_backend_b_routes -->|"uses"| node_backend_b_state
node_backend_a_db -->|"transactions"| node_postgres
node_backend_b_db -->|"transactions"| node_postgres
node_postgres -->|"contains"| node_schema
node_dashboard -.->|"admin/tests"| node_backend_a_routes
node_dashboard -.->|"admin/tests"| node_backend_b_routes
node_compose -->|"starts"| node_frontend_app
node_compose -->|"starts"| node_nginx_image
node_compose -->|"starts"| node_backend_a_img
node_compose -->|"starts"| node_backend_b_img
node_compose -->|"starts"| node_postgres
node_backend_a_app -.->|"peer replica"| node_backend_b_app
node_backend_a_routes -.->|"equivalent"| node_backend_b_routes

click node_browser_ui "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/src/pages/index.astro"
click node_dashboard "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/src/components/Dashboard.tsx"
click node_frontend_app "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/package.json"
click node_nginx_conf "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/nginx/nginx.conf"
click node_nginx_image "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/nginx/Dockerfile"
click node_backend_a_app "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/index.ts"
click node_backend_a_routes "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/routes/reserva.ts"
click node_backend_a_state "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/state.ts"
click node_backend_a_db "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/db.ts"
click node_backend_b_app "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/index.ts"
click node_backend_b_routes "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/routes/reserva.ts"
click node_backend_b_state "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/state.ts"
click node_backend_b_db "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/db.ts"
click node_postgres "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/database/init.sql"
click node_schema "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/database/init.sql"
click node_compose "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/docker-compose.yml"
click node_backend_a_img "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/backend-a/Dockerfile"
click node_backend_b_img "https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/backend-b/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_ui,node_dashboard,node_frontend_app toneBlue
class node_nginx_conf,node_nginx_image toneAmber
class node_backend_a_app,node_backend_a_routes,node_backend_a_state,node_backend_a_db,node_backend_b_app,node_backend_b_routes,node_backend_b_state,node_backend_b_db toneMint
class node_postgres,node_schema toneRose
class node_compose,node_backend_a_img,node_backend_b_img toneIndigo
```

## Components

### Frontend

Operator dashboard and browser UI

- [Browser UI](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/src/pages/index.astro): client · Operator-facing dashboard in the browser · `frontend/src/pages/index.astro`
- [Dashboard](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/src/components/Dashboard.tsx): react component · Polls status and triggers tests · `frontend/src/components/Dashboard.tsx`
- [Astro app](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/frontend/package.json): frontend app · Serves the browser dashboard · `frontend/package.json`

### Edge

Public ingress and request routing

- [Ingress](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/nginx/nginx.conf): nginx config · Public entrypoint and backend load balancing · `nginx/nginx.conf`
- [Nginx image](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/nginx/Dockerfile): container image · Reverse proxy runtime · `nginx/Dockerfile`

### Backends

Interchangeable application replicas

- [Backend A](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/index.ts): node service · Replica A API and reservation worker · `backend-a/src/index.ts`
- [A routes](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/routes/reserva.ts): api routes · Health, events, reservation, admin, autoscale · `backend-a/src/routes/reserva.ts`
- [A state](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/state.ts): runtime state · Local simulation and health toggles · `backend-a/src/state.ts`
- [A db](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-a/src/db.ts): db access · PostgreSQL access and transactions · `backend-a/src/db.ts`
- [Backend B](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/index.ts): node service · Replica B API and reservation worker · `backend-b/src/index.ts`
- [B routes](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/routes/reserva.ts): api routes · Health, events, reservation, admin, autoscale · `backend-b/src/routes/reserva.ts`
- [B state](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/state.ts): runtime state · Local simulation and health toggles · `backend-b/src/state.ts`
- [B db](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/backend-b/src/db.ts): db access · PostgreSQL access and transactions · `backend-b/src/db.ts`

### Data

Shared persistence and schema

- [PostgreSQL](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/database/init.sql): database · System of record and contention coordinator · `database/init.sql`
- [Schema](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/database/init.sql): init sql · Tickets, events, and virtual queue tables · `database/init.sql`

### Deployment

Container orchestration and runtime images

- [Compose](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/blob/main/docker-compose.yml): deployment spec · Defines the full multi-container topology · `docker-compose.yml`
- [A image](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/backend-a/Dockerfile): container image · Builds backend-a runtime image · `backend-a/Dockerfile`
- [B image](https://github.com/drezzgo/oneticket-sistema-distribuido-docker/tree/main/backend-b/Dockerfile): container image · Builds backend-b runtime image · `backend-b/Dockerfile`

## Connections

- Browser UI → Dashboard: renders · Dashboard is the main browser surface
- Dashboard → Ingress: API calls · Status polling and control actions go through Nginx
- Astro app → Browser UI: serves · Astro frontend delivers the dashboard UI
- Ingress → Backend A: routes to · Load-balances requests across backend replicas
- Ingress → Backend B: routes to · Load-balances requests across backend replicas
- Backend A → A routes: mounts · HTTP server exposes the route modules
- Backend B → B routes: mounts · HTTP server exposes the route modules
- A routes → A db: reads/writes · Reservation and event routes use database transactions
- B routes → B db: reads/writes · Reservation and event routes use database transactions
- A routes → A state: uses · Admin and autoscale endpoints change local node state
- B routes → B state: uses · Admin and autoscale endpoints change local node state
- A db → PostgreSQL: transactions · Concurrency control is enforced in PostgreSQL
- B db → PostgreSQL: transactions · Concurrency control is enforced in PostgreSQL
- PostgreSQL → Schema: contains · Schema defines reservation tables and queue state
- Dashboard → A routes: admin/tests · Injects load, failover, and control actions through the API
- Dashboard → B routes: admin/tests · Injects load, failover, and control actions through the API
- Compose → Astro app: starts · Docker Compose runs the frontend container
- Compose → Nginx image: starts · Docker Compose runs the ingress container
- Compose → A image: starts · Docker Compose runs backend replica A
- Compose → B image: starts · Docker Compose runs backend replica B
- Compose → PostgreSQL: starts · Docker Compose runs the database container
- Backend A → Backend B: peer replica · Equivalent active-active backend services
- A routes → B routes: equivalent · Same API surface on both replicas
