# unmangeablealore/turnos-ganagana architecture

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

- Interactive diagram: https://gitdiagram.com/unmangeablealore/turnos-ganagana
- Repository: https://github.com/unmangeablealore/turnos-ganagana

## Overview

GanaGana is a four-counter queue system with customer-facing counter selection, a public spoken display, and administrator operations. The documented request path is React views → API client → Express routes/controllers → models → persistent store; Socket.IO separately coordinates live state and counter occupancy. The graph preserves authentication integrations, administration, scheduling, and live presence. Some UI and service modules are listed but unsampled, so their internal links are omitted unless documented or visible in the source index.

Main entry points: [`server/routes`](https://github.com/unmangeablealore/turnos-ganagana/tree/main/server/routes) (HTTP routes), [`client/src/views/pages`](https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/views/pages) (Queue pages), [`server/controllers/caja.controller.js`](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/caja.controller.js) (Counter operations), [`server/controllers/socket.controller.js`](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/socket.controller.js) (Socket events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_pages["Queue pages"]
  node_adminui["Admin console"]
  node_api["API client<br/>[api.ts]"]
  node_client_models["Client models"]
  node_voice["Spoken calls<br/>[voz.ts]"]
  node_socket_client["Socket hook<br/>[useSocket.ts]"]
end

subgraph group_server["HTTP application"]
  node_http_routes["HTTP routes"]
  node_auth["Authentication<br/>[auth.controller.js]"]
  node_admin_ops["Admin operations"]
  node_queue_ops["Queue operations"]
  node_counter_ops["Counter operations<br/>[caja.controller.js]"]
  node_config_ops["System settings"]
  node_system_ops["Day management"]
  node_captcha["CAPTCHA check<br/>[captcha.service.js]"]
  node_oauth["OAuth providers<br/>[oauth.service.js]"]
end

subgraph group_realtime["Live queue"]
  node_socket_server["Socket events"]
  node_broadcast["Realtime service"]
  node_presence["Device presence<br/>[presencia.model.js]"]
end

subgraph group_domain["Domain and persistence"]
  node_queue_model["Queue state<br/>[turno.model.js]"]
  node_settings_model["Settings model"]
  node_admin_model["Administrator model"]
  node_day_service["Jornada scheduler<br/>[jornada.service.js]"]
  node_store[("Queue store<br/>[store.js]")]
end

node_users(("Queue users"))
node_postgres[("Postgres<br/>[postgres.js]")]
node_external_oauth(("OAuth provider<br/>external system"))
node_external_captcha(("CAPTCHA provider<br/>external system"))

node_users -->|"use"| node_pages
node_pages -->|"request via"| node_api
node_api -->|"request"| node_http_routes
node_http_routes -->|"routes to"| node_auth
node_http_routes -->|"routes to"| node_admin_ops
node_http_routes -->|"routes to"| node_queue_ops
node_http_routes -->|"routes to"| node_counter_ops
node_http_routes -->|"routes to"| node_config_ops
node_http_routes -->|"routes to"| node_system_ops
node_auth -->|"verifies"| node_captcha
node_auth -->|"delegates to"| node_oauth
node_auth -->|"looks up"| node_admin_model
node_admin_ops -->|"uses"| node_admin_model
node_queue_ops -->|"uses"| node_queue_model
node_counter_ops -->|"uses"| node_queue_model
node_counter_ops -->|"uses"| node_settings_model
node_counter_ops -->|"uses"| node_presence
node_counter_ops -->|"emits updates"| node_broadcast
node_config_ops -->|"uses"| node_settings_model
node_config_ops -->|"emits updates"| node_broadcast
node_system_ops -->|"delegates to"| node_day_service
node_day_service -->|"uses"| node_queue_model
node_day_service -->|"uses"| node_settings_model
node_day_service -->|"emits updates"| node_broadcast
node_queue_model -->|"persists via"| node_store
node_settings_model -->|"reads and writes"| node_store
node_admin_model -->|"uses"| node_store
node_store -->|"syncs data"| node_postgres
node_pages -->|"uses live state"| node_socket_client
node_socket_client -->|"Socket.IO events"| node_socket_server
node_socket_server -->|"reads state"| node_queue_model
node_socket_server -->|"reads config"| node_settings_model
node_socket_server -->|"tracks devices"| node_presence
node_socket_server -->|"delegates occupancy"| node_broadcast
node_broadcast -->|"calculates presence"| node_presence
node_pages -->|"uses"| node_client_models
node_pages -->|"uses spoken calls"| node_voice
node_adminui -.->|"calls API"| node_api
node_users -.->|"admin sign-in"| node_auth
node_oauth -.->|"redirects to"| node_external_oauth
node_captcha -.->|"verifies with"| node_external_captcha

click node_pages "https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/views/pages"
click node_adminui "https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/views/admin"
click node_api "https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/api.ts"
click node_client_models "https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/models"
click node_voice "https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/voz.ts"
click node_socket_client "https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/useSocket.ts"
click node_http_routes "https://github.com/unmangeablealore/turnos-ganagana/tree/main/server/routes"
click node_auth "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/auth.controller.js"
click node_admin_ops "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/administradores.controller.js"
click node_queue_ops "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/turno.controller.js"
click node_counter_ops "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/caja.controller.js"
click node_config_ops "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/config.controller.js"
click node_system_ops "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/sistema.controller.js"
click node_captcha "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/captcha.service.js"
click node_oauth "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/oauth.service.js"
click node_socket_server "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/socket.controller.js"
click node_broadcast "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/tiempoReal.service.js"
click node_presence "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/presencia.model.js"
click node_queue_model "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/turno.model.js"
click node_settings_model "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/configuracion.model.js"
click node_admin_model "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/administrador.model.js"
click node_day_service "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/jornada.service.js"
click node_store "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/store.js"
click node_postgres "https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/config/postgres.js"

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_pages,node_adminui,node_api,node_client_models,node_voice,node_socket_client toneBlue
class node_http_routes,node_auth,node_admin_ops,node_queue_ops,node_counter_ops,node_config_ops,node_system_ops,node_captcha,node_oauth,node_postgres toneAmber
class node_socket_server,node_broadcast,node_presence toneMint
class node_queue_model,node_settings_model,node_admin_model,node_day_service,node_store,node_users toneRose
class node_external_oauth,node_external_captcha toneIndigo
```

## Components

### React client

- [Queue pages](https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/views/pages): `client/src/views/pages`
- [Admin console](https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/views/admin): `client/src/views/admin`
- [API client](https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/api.ts): `client/src/controllers/api.ts`
- [Client models](https://github.com/unmangeablealore/turnos-ganagana/tree/main/client/src/models): `client/src/models`
- [Spoken calls](https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/voz.ts): `client/src/controllers/voz.ts`
- [Socket hook](https://github.com/unmangeablealore/turnos-ganagana/blob/main/client/src/controllers/useSocket.ts): `client/src/controllers/useSocket.ts`

### HTTP application

- [HTTP routes](https://github.com/unmangeablealore/turnos-ganagana/tree/main/server/routes): `server/routes`
- [Authentication](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/auth.controller.js): `server/controllers/auth.controller.js`
- [Admin operations](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/administradores.controller.js): `server/controllers/administradores.controller.js`
- [Queue operations](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/turno.controller.js): `server/controllers/turno.controller.js`
- [Counter operations](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/caja.controller.js): `server/controllers/caja.controller.js`
- [System settings](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/config.controller.js): `server/controllers/config.controller.js`
- [Day management](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/sistema.controller.js): `server/controllers/sistema.controller.js`
- [CAPTCHA check](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/captcha.service.js): `server/services/captcha.service.js`
- [OAuth providers](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/oauth.service.js): `server/services/oauth.service.js`

### Live queue

- [Socket events](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/controllers/socket.controller.js): `server/controllers/socket.controller.js`
- [Realtime service](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/tiempoReal.service.js): `server/services/tiempoReal.service.js`
- [Device presence](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/presencia.model.js): `server/models/presencia.model.js`

### Domain and persistence

- [Queue state](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/turno.model.js): `server/models/turno.model.js`
- [Settings model](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/configuracion.model.js): `server/models/configuracion.model.js`
- [Administrator model](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/administrador.model.js): `server/models/administrador.model.js`
- [Jornada scheduler](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/services/jornada.service.js): `server/services/jornada.service.js`
- [Queue store](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/models/store.js): `server/models/store.js`

### Other components

- **Queue users**
- [Postgres](https://github.com/unmangeablealore/turnos-ganagana/blob/main/server/config/postgres.js): `server/config/postgres.js`
- **OAuth provider**: external system
- **CAPTCHA provider**: external system

## Connections

- Queue users → Queue pages: use (evidence: `README.md`)
- Queue pages → API client: request via (evidence: `README.md`)
- API client → HTTP routes: request (evidence: `README.md`)
- HTTP routes → Authentication: routes to (evidence: `server/routes/auth.routes.js`)
- HTTP routes → Admin operations: routes to (evidence: `server/routes/auth.routes.js`)
- HTTP routes → Queue operations: routes to (evidence: `server/routes/api.routes.js`)
- HTTP routes → Counter operations: routes to (evidence: `server/routes/api.routes.js`)
- HTTP routes → System settings: routes to (evidence: `server/routes/api.routes.js`)
- HTTP routes → Day management: routes to (evidence: `server/routes/api.routes.js`)
- Authentication → CAPTCHA check: verifies (evidence: `server/controllers/auth.controller.js`)
- Authentication → OAuth providers: delegates to (evidence: `server/controllers/auth.controller.js`)
- Authentication → Administrator model: looks up (evidence: `server/controllers/auth.controller.js`)
- Admin operations → Administrator model: uses (evidence: `server/controllers/administradores.controller.js`)
- Queue operations → Queue state: uses (evidence: `server/controllers/turno.controller.js`)
- Counter operations → Queue state: uses (evidence: `server/controllers/caja.controller.js`)
- Counter operations → Settings model: uses (evidence: `server/controllers/caja.controller.js`)
- Counter operations → Device presence: uses (evidence: `server/controllers/caja.controller.js`)
- Counter operations → Realtime service: emits updates (evidence: `server/controllers/caja.controller.js`)
- System settings → Settings model: uses (evidence: `server/controllers/config.controller.js`)
- System settings → Realtime service: emits updates (evidence: `server/controllers/config.controller.js`)
- Day management → Jornada scheduler: delegates to (evidence: `server/controllers/sistema.controller.js`)
- Jornada scheduler → Queue state: uses (evidence: `server/services/jornada.service.js`)
- Jornada scheduler → Settings model: uses (evidence: `server/services/jornada.service.js`)
- Jornada scheduler → Realtime service: emits updates (evidence: `server/services/jornada.service.js`)
- Queue state → Queue store: persists via (evidence: `server/models/turno.model.js`)
- Settings model → Queue store: reads and writes (evidence: `server/models/configuracion.model.js`)
- Administrator model → Queue store: uses (evidence: `server/models/administrador.model.js`)
- Queue store → Postgres: syncs data (evidence: `server/models/store.js`)
- Queue pages → Socket hook: uses live state (evidence: `client/src/views/pages/CajaPage.tsx`)
- Socket hook → Socket events: Socket.IO events (evidence: `server/controllers/socket.controller.js`)
- Socket events → Queue state: reads state (evidence: `server/controllers/socket.controller.js`)
- Socket events → Settings model: reads config (evidence: `server/controllers/socket.controller.js`)
- Socket events → Device presence: tracks devices (evidence: `server/controllers/socket.controller.js`)
- Socket events → Realtime service: delegates occupancy (evidence: `server/controllers/socket.controller.js`)
- Realtime service → Device presence: calculates presence (evidence: `server/services/tiempoReal.service.js`)
- Queue pages → Client models: uses (evidence: `client/src/views/pages/CajaPage.tsx`)
- Queue pages → Spoken calls: uses spoken calls (evidence: `client/src/views/pages/DisplayPage.tsx`)
- Admin console → API client: calls API
- Queue users → Authentication: admin sign-in
- OAuth providers → OAuth provider: redirects to
- CAPTCHA check → CAPTCHA provider: verifies with
