# limberwq/proyecto-software-final-semestre architecture

> Architecture diagram of the GitHub repository limberwq/proyecto-software-final-semestre, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/limberwq/proyecto-software-final-semestre
- Repository: https://github.com/limberwq/proyecto-software-final-semestre

## Overview

1. **Repository shape**
   - This repo contains two cooperating Python services: **`segip/`** and **`tse/`**.
   - The overall system is a **state-backed election platform** with a blockchain ledger for vote integrity and a separate identity/citizen registry integration.

2. **`segip/` service**
   - `segip` is a small standalone backend that looks like a **SEGIP identity mock/service**.
   - It has its own `app.py`, `auth.py`, `models.py`, `config.py`, and `seed_data.py`, so it behaves like an external dependency the election system calls to validate voters or fetch citizen data.
   - This service is isolated from the main election domain, which makes it a clean boundary for identity verification.

3. **`tse/backend` as the core application**
   - The main system lives under `tse/backend/app`.
   - It is organized in a classic Flask-style layering:
     - **routes** for HTTP endpoints,
     - **services** for business rules,
     - **models** for persistence,
     - **blockchain** for ledger logic,
     - **views** for server-rendered pages,
     - **decorators/extensions/config** for cross-cutting concerns.
   - `run.py` is the entrypoint for the backend app.

4. **Persistent storage layer**
   - The relational domain is modeled with entities such as `usuario`, `election`, `candidate`, `recinto`, `padron`, `conteo`, `recibo`, `bloque`, and `audit_log`.
   - This suggests the system keeps both operational data (users, elections, polling stations, voter registry, vote counts) and audit data in a database.
   - `init_final.sql` is a bootstrap script for initializing the schema/data, which matters for deployment and reproducibility.

5. **Blockchain subsystem**
   - The `blockchain/` package implements the election ledger using `block.py`, `chain.py`, `crypto.py`, and `node_sync.py`.
   - Chain snapshots are stored on disk under `tse/backend/blockchain_data/eleccion_005/chain.json` and `eleccion_006/chain.json`, indicating **per-election ledger persistence** outside the relational DB.
   - The ledger is therefore a separate integrity boundary: vote events are recorded in the database and mirrored/anchored in an append-only chain for auditing.

6. **Business service layer**
   - Services such as `vote_service`, `conteo_service`, `padron_service`, `election_service`, `auth_service`, `candidato_service`, `audit_service`, and `segip_service` centralize domain logic.
   - This is where the app likely validates voters, enforces election state, updates counts, and coordinates writes across the DB, blockchain, and SEGIP lookup.
   - `segip_service` is the integration point from the election system to the separate SEGIP service.

7. **HTTP/API surface**
   - The `routes/` package exposes functional endpoints for `auth`, `elections`, `candidates`, `padron`, `votes`, `results`, `audit`, and `kiosk`.
   - The route names show two access patterns:
     - **API/operational endpoints** for election workflows,
     - **special-purpose endpoints** for kiosk voting, audit verification, and results reporting.

8. **Server-rendered UI**
   - The `views/` package plus `tse/frontend/templates` indicates the app also serves **HTML pages**, not just JSON APIs.
   - There are distinct UI areas for:
     - **admin**: elections, candidates, recintos, users, padrón,
     - **operator**: polling-day operations and verification,
     - **audit**: chain inspection and receipt verification,
     - **results**: election result dashboards,
     - **voter**: ballot/casting flow.
   - `web_decorators.py` suggests role-based access control for these screens.

9. **Main end-to-end data flow**
   - A voter or operator starts in the frontend UI.
   - The backend authenticates the user, checks eligibility against the padrón, and may consult the SEGIP service through `segip_service`.
   - When a vote is cast, the system writes operational records, updates counts, and appends the event to the blockchain ledger.
   - A receipt (`recibo`) is produced so the vote can later be independently verified.

10. **Audit and verification path**
   - The audit subsystem is a first-class boundary, not an afterthought.
   - Audit pages read chain data and receipts to verify that a vote exists, that the chain is intact, and that no tampering occurred.
   - `audit_log` and the blockchain files together support traceability from user action to immutable ledger state.

11. **Results path**
   - Election results are separated into their own route/view/service flow.
   - Results are likely derived from `conteo` and election-specific data rather than directly from raw ballots, which keeps reporting independent from the ballot-casting UX.
   - This supports both live dashboards and post-election reporting.

12. **Deployment/runtime**
   - Both services are containerized with Docker (`segip/Dockerfile`, `tse/Dockerfile`) and orchestrated via `docker-compose.yml`.
   - The repository is therefore designed for multi-container deployment: one container for identity/SEGIP and one for the election platform, with persistent blockchain data and database initialization handled at startup.

13. **Architecture summary for a diagram**
   - Draw three main boundaries:
     - **SEGIP identity service**,
     - **TSE backend application**,
     - **persistent stores**: relational DB + filesystem blockchain snapshots.
   - Inside TSE, show the flow: **UI / API routes → services → models + blockchain + SEGIP integration**.
   - Keep audit and results as separate read paths off the same data sources, because they are operationally distinct from vote casting.

Main entry points: [`tse/backend/app/services`](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/services) (Domain services), [`tse/backend/app/views`](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/views) (Web views), [`tse/backend/run.py`](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/run.py) (Backend entry), [`tse/backend/app/blockchain`](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/blockchain) (Ledger engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_segip["SEGIP identity"]
  node_segip_app["SEGIP API<br/>python service<br/>[app.py]"]
  node_segip_auth["SEGIP auth<br/>auth helper<br/>[auth.py]"]
  node_segip_models["Citizen model<br/>data model<br/>[models.py]"]
  node_segip_config["SEGIP config<br/>[config.py]"]
end

subgraph group_tse_backend["TSE backend"]
  node_tse_run["Backend entry<br/>flask entrypoint<br/>[run.py]"]
  node_routes["HTTP routes<br/>api layer"]
  node_services["Domain services<br/>business layer"]
  node_models[("DB models<br/>orm layer")]
  node_blockchain{{"Ledger engine<br/>blockchain package"}}
  node_web_views["Web views<br/>server UI"]
  node_app_config["App config<br/>[config.py]"]
  node_extensions["Extensions<br/>flask infra<br/>[extensions.py]"]
  node_decorators["Access guards<br/>rbac helpers<br/>[decorators.py]"]
end

subgraph group_frontend["Web UI"]
  node_admin_ui["Admin screens<br/>frontend pages"]
  node_operator_ui["Operator screens<br/>frontend pages"]
  node_audit_ui["Audit screens<br/>frontend pages"]
  node_results_ui["Results screens<br/>frontend pages"]
  node_voter_ui["Voter screen<br/>frontend page"]
end

subgraph group_storage["Persistent state"]
  node_db_schema[("Election DB<br/>relational store<br/>[init_final.sql]")]
  node_chain_store["Chain snapshots<br/>filesystem store"]
end

node_docker["Compose runtime<br/>deployment<br/>[docker-compose.yml]"]

node_docker -->|"runs"| node_segip_app
node_docker -->|"runs"| node_tse_run
node_tse_run -->|"mounts"| node_routes
node_tse_run -->|"uses"| node_services
node_tse_run -->|"uses"| node_models
node_tse_run -->|"uses"| node_blockchain
node_tse_run -->|"serves"| node_web_views
node_routes -->|"calls"| node_services
node_services -->|"reads/writes"| node_models
node_services -->|"anchors"| node_blockchain
node_services -->|"verifies"| node_segip_app
node_services -->|"stores"| node_db_schema
node_blockchain -->|"persists"| node_chain_store
node_web_views -->|"protects"| node_decorators
node_web_views -->|"renders"| node_admin_ui
node_web_views -->|"renders"| node_operator_ui
node_web_views -->|"renders"| node_audit_ui
node_web_views -->|"renders"| node_results_ui
node_web_views -->|"renders"| node_voter_ui
node_services -->|"configures"| node_app_config
node_services -->|"uses"| node_extensions

click node_segip_app "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/app.py"
click node_segip_auth "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/auth.py"
click node_segip_models "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/models.py"
click node_segip_config "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/config.py"
click node_tse_run "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/run.py"
click node_routes "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/routes"
click node_services "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/services"
click node_models "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/models"
click node_blockchain "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/blockchain"
click node_web_views "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/views"
click node_app_config "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/config.py"
click node_extensions "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/extensions.py"
click node_decorators "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/decorators.py"
click node_db_schema "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/init_final.sql"
click node_chain_store "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/blockchain_data"
click node_docker "https://github.com/limberwq/proyecto-software-final-semestre/blob/main/docker-compose.yml"
click node_admin_ui "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/admin"
click node_operator_ui "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/operator"
click node_audit_ui "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/audit"
click node_results_ui "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/results"
click node_voter_ui "https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/voter"

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_segip_app,node_segip_auth,node_segip_models,node_segip_config toneBlue
class node_tse_run,node_routes,node_services,node_models,node_blockchain,node_web_views,node_app_config,node_extensions,node_decorators toneAmber
class node_admin_ui,node_operator_ui,node_audit_ui,node_results_ui,node_voter_ui toneMint
class node_db_schema,node_chain_store toneRose
class node_docker toneNeutral
```

## Components

### SEGIP identity

External citizen registry mock/service

- [SEGIP API](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/app.py): python service · Identity lookup and validation service · `segip/app.py`
- [SEGIP auth](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/auth.py): auth helper · Auth and access helpers for SEGIP · `segip/auth.py`
- [Citizen model](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/models.py): data model · SEGIP-side citizen data structures · `segip/models.py`
- [SEGIP config](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/segip/config.py): config · Service settings and environment config · `segip/config.py`

### TSE backend

Main election application

- [Backend entry](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/run.py): flask entrypoint · Starts the main election backend · `tse/backend/run.py`
- [HTTP routes](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/routes): api layer · Election, auth, audit, results, kiosk endpoints · `tse/backend/app/routes`
- [Domain services](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/services): business layer · Business rules and orchestration · `tse/backend/app/services`
- [DB models](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/models): orm layer · Relational election and audit entities · `tse/backend/app/models`
- [Ledger engine](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/blockchain): blockchain package · Vote chain, crypto, and node sync · `tse/backend/app/blockchain`
- [Web views](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/app/views): server UI · Role-based rendered pages and panels · `tse/backend/app/views`
- [App config](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/config.py): config · Backend runtime configuration · `tse/backend/app/config.py`
- [Extensions](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/extensions.py): flask infra · Shared app extensions and integrations · `tse/backend/app/extensions.py`
- [Access guards](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/tse/backend/app/decorators.py): rbac helpers · Web decorators for protected screens · `tse/backend/app/decorators.py`

### Web UI

Server-rendered operator/admin/voter screens

- [Admin screens](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/admin): frontend pages · Administration and maintenance views · `tse/frontend/templates/admin`
- [Operator screens](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/operator): frontend pages · Polling-day operator workflow pages · `tse/frontend/templates/operator`
- [Audit screens](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/audit): frontend pages · Chain and receipt verification pages · `tse/frontend/templates/audit`
- [Results screens](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/results): frontend pages · Election result dashboards and reports · `tse/frontend/templates/results`
- [Voter screen](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/frontend/templates/voter): frontend page · Ballot casting interface · `tse/frontend/templates/voter`

### Persistent state

Database and blockchain snapshots

- [Election DB](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/init_final.sql): relational store · Users, elections, padrón, counts, receipts, audit · `init_final.sql`
- [Chain snapshots](https://github.com/limberwq/proyecto-software-final-semestre/tree/main/tse/backend/blockchain_data): filesystem store · Per-election blockchain JSON snapshots · `tse/backend/blockchain_data`

### Other components

- [Compose runtime](https://github.com/limberwq/proyecto-software-final-semestre/blob/main/docker-compose.yml): deployment · Container orchestration for SEGIP and TSE · `docker-compose.yml`

## Connections

- Compose runtime → SEGIP API: runs · Starts identity service container
- Compose runtime → Backend entry: runs · Starts main backend container
- Backend entry → HTTP routes: mounts · Registers HTTP endpoints
- Backend entry → Domain services: uses · Wires domain logic into routes
- Backend entry → DB models: uses · Connects persistence layer
- Backend entry → Ledger engine: uses · Initializes ledger subsystem
- Backend entry → Web views: serves · Exposes HTML UI
- HTTP routes → Domain services: calls · Delegates request handling
- Domain services → DB models: reads/writes · Persists election state and audit data
- Domain services → Ledger engine: anchors · Appends vote events to chain
- Domain services → SEGIP API: verifies · Checks citizen identity through SEGIP
- Domain services → Election DB: stores · Operational and audit records
- Ledger engine → Chain snapshots: persists · Writes per-election chain snapshots
- Web views → Access guards: protects · Applies role-based access control
- Web views → Admin screens: renders · Admin workflows and management screens
- Web views → Operator screens: renders · Polling-day operator screens
- Web views → Audit screens: renders · Audit and verification screens
- Web views → Results screens: renders · Results dashboards
- Web views → Voter screen: renders · Ballot casting screen
- Domain services → App config: configures · Loads backend settings
- Domain services → Extensions: uses · Shares flask extensions