limberwq/proyecto-software-final-semestre

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.