How drezzgo/oneticket-sistema-distribuido-docker works
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 Compose · routes/reserva.ts A routes · routes/reserva.ts B routes · Dashboard.tsx Dashboard
Components 18
Frontend
Operator dashboard and browser UI
- Browser UI · Operator-facing dashboard in the browser
frontend/src/pages/index.astro - Dashboard · Polls status and triggers tests
frontend/src/components/Dashboard.tsx - Astro app · Serves the browser dashboard
frontend/package.json
Edge
Public ingress and request routing
- Ingress · Public entrypoint and backend load balancing
nginx/nginx.conf - Nginx image · Reverse proxy runtime
nginx/Dockerfile
Backends
Interchangeable application replicas
- Backend A · Replica A API and reservation worker
backend-a/src/index.ts - A routes · Health, events, reservation, admin, autoscale
backend-a/src/routes/reserva.ts - A state · Local simulation and health toggles
backend-a/src/state.ts - A db · PostgreSQL access and transactions
backend-a/src/db.ts - Backend B · Replica B API and reservation worker
backend-b/src/index.ts - B routes · Health, events, reservation, admin, autoscale
backend-b/src/routes/reserva.ts - B state · Local simulation and health toggles
backend-b/src/state.ts - B db · PostgreSQL access and transactions
backend-b/src/db.ts
Data
Shared persistence and schema
- PostgreSQL · System of record and contention coordinator
database/init.sql - Schema · Tickets, events, and virtual queue tables
database/init.sql
Connections 23
- 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