# dvleu/proyectoinvestigacion architecture

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

- Interactive diagram: https://gitdiagram.com/dvleu/proyectoinvestigacion
- Repository: https://github.com/dvleu/proyectoinvestigacion

## Overview

1. **Overall shape**
   - This is a small monolithic attendance system built around a single Python/Flask application.
   - The app sits between three main domains: an NFC reader, a MySQL database, and a browser-based dashboard.

2. **Runtime entry point**
   - `src/app/app.py` is the main executable.
   - From the README, it starts the Flask server, exposes the HTTP API, serves the web UI, and can run the NFC-reading flow in the same process.
   - The project is meant to be launched as one local service on port `5000`.

3. **Application layer boundaries**
   - `config.py` holds Flask and SQLAlchemy configuration, including database connectivity.
   - `models.py` defines the ORM entities that map to the attendance schema.
   - `routes.py` defines the HTTP endpoints.
   - `services.py` contains the business logic: deciding whether a scanned card becomes an entry or exit event, and handling NFC-related operations.

4. **Core data model**
   - The schema centers on four tables:
     - `usuarios` for student/person records
     - `tarjetas_nfc` for card UIDs associated with users
     - `salones` for rooms or reader locations
     - `registros_acceso` for the event history
   - The important relationship boundary is that a user can have multiple cards, while each access record links a user, a card, a room, and an event type.

5. **Primary data flow: NFC scan to attendance record**
   - A UID is read from a physical NFC card or provided through the API.
   - The service layer looks up the UID in `tarjetas_nfc`, resolves the linked user, and determines whether the next event should be `ENTRADA` or `SALIDA` based on the user’s last record for the day.
   - The resulting row is written to `registros_acceso` and then made visible through the API and web UI.

6. **Secondary data flow: REST API**
   - The API is centered in `routes.py` and exposes CRUD-like endpoints for users, cards, rooms, and access records.
   - The key operational endpoint is `POST /acceso`, which accepts a UID and triggers the same attendance logic used by the reader.
   - This makes the NFC hardware optional for development, since the system can be driven by HTTP calls.

7. **Web interface**
   - `src/front/index.html` is a lightweight browser UI, likely a single-page interface with JavaScript polling or fetching data from the Flask API.
   - The README indicates it is served at `/web`, so the UI is not a separate frontend app or build pipeline; it is embedded into the backend deployment.
   - Its main role is operational visibility: current activity and recent records in near real time.

8. **Database infrastructure**
   - `docker-compose.yml` provides the persistence layer and admin tooling.
   - It runs MySQL 8.0 plus phpMyAdmin, with the database exposed on host port `3307` and phpMyAdmin on `8080`.
   - Persistence is handled by a Docker volume, so the application state survives container restarts.

9. **Schema and seed assets**
   - `src/Schema/Schema.sql` is the canonical database definition.
   - `seed.sql` indicates there is preloaded data for local setup or demo usage.
   - These files form the boundary between application code and database provisioning.

10. **Hardware integration boundary**
   - The project targets an ACS ACR122U NFC reader and compatible card types.
   - The hardware dependency is isolated to the NFC reading path; the rest of the system remains usable through the REST API and simulated UID inputs.
   - This separation is important for the architecture: physical device I/O is not the same boundary as persistence or presentation.

11. **Operational modes**
   - The README describes a “simulator” mode for development without hardware.
   - That suggests the service layer is designed to accept either real NFC input or test input, while preserving the same downstream attendance logic.
   - This is useful for understanding the repo as a system with interchangeable input sources but one shared write path.

12. **Key diagramming takeaway**
   - The cleanest architecture diagram would show:
     - NFC reader / simulated UID input
     - Flask app with route layer and service layer
     - SQLAlchemy models against MySQL
     - Browser UI consuming the same Flask API
     - Docker-managed MySQL and phpMyAdmin as infrastructure
   - The main architectural boundary is between input capture, business rules, and persistence, with the Flask app acting as the central orchestrator.

Main entry points: [`src/app/services.py`](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/services.py) (Services), [`src/app/app.py`](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/app.py) (App entry), [`src/app/routes.py`](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/routes.py) (Routes), [`docker-compose.yml`](https://github.com/dvleu/proyectoinvestigacion/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flask App"]
  node_src_app_app_py["App entry<br/>Flask runtime<br/>[app.py]"]
  node_src_app_config_py["Config<br/>[config.py]"]
  node_src_app_routes_py["Routes<br/>HTTP API<br/>[routes.py]"]
  node_src_app_services_py["Services<br/>Business logic<br/>[services.py]"]
  node_src_app_models_py["Models<br/>ORM schema<br/>[models.py]"]
  node_nfc_input(("NFC input<br/>Device/simulated"))
end

subgraph group_ui["Browser UI"]
  node_src_front_index_html["Web UI<br/>Browser client<br/>[index.html]"]
end

subgraph group_infra["Infrastructure"]
  node_mysql_db[("MySQL<br/>Database")]
  node_phpmyadmin["phpMyAdmin<br/>Admin UI"]
  node_docker_compose["Compose<br/>Container stack<br/>[docker-compose.yml]"]
end

subgraph group_db["Database Assets"]
  node_src_schema_schema_sql["Schema SQL<br/>DDL<br/>[Schema.sql]"]
  node_seed_sql["Seed data<br/>Bootstrap data<br/>[seed.sql]"]
end

node_src_app_app_py -->|"loads config"| node_src_app_config_py
node_src_app_app_py -->|"registers API"| node_src_app_routes_py
node_src_app_app_py -->|"uses logic"| node_src_app_services_py
node_src_app_app_py -->|"serves UI"| node_src_front_index_html
node_src_app_routes_py -->|"delegates"| node_src_app_services_py
node_src_app_services_py -->|"queries/writes"| node_src_app_models_py
node_src_app_models_py -->|"maps to"| node_mysql_db
node_nfc_input -->|"UID scan"| node_src_app_services_py
node_src_front_index_html -->|"fetches API"| node_src_app_routes_py
node_docker_compose -->|"provisions"| node_mysql_db
node_docker_compose -->|"provisions"| node_phpmyadmin
node_src_schema_schema_sql -->|"defines schema"| node_mysql_db
node_seed_sql -->|"loads data"| node_mysql_db
node_src_app_services_py -->|"attendance write"| node_mysql_db

click node_src_app_app_py "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/app.py"
click node_src_app_config_py "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/config.py"
click node_src_app_routes_py "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/routes.py"
click node_src_app_services_py "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/services.py"
click node_src_app_models_py "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/models.py"
click node_src_front_index_html "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/front/index.html"
click node_docker_compose "https://github.com/dvleu/proyectoinvestigacion/blob/main/docker-compose.yml"
click node_src_schema_schema_sql "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/Schema/Schema.sql"
click node_seed_sql "https://github.com/dvleu/proyectoinvestigacion/blob/main/src/Schema/seed.sql"

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_src_app_app_py,node_src_app_config_py,node_src_app_routes_py,node_src_app_services_py,node_src_app_models_py,node_nfc_input toneBlue
class node_src_front_index_html toneAmber
class node_mysql_db,node_phpmyadmin,node_docker_compose toneMint
class node_src_schema_schema_sql,node_seed_sql toneRose
```

## Components

### Flask App

Core Python application that serves the API and attendance workflow.

- [App entry](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/app.py): Flask runtime · Main executable that starts the server and orchestrates the attendance flow. · `src/app/app.py`
- [Config](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/config.py): Flask/DB config · Application and SQLAlchemy configuration, including database connection settings. · `src/app/config.py`
- [Routes](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/routes.py): HTTP API · REST endpoints for users, cards, rooms, and access records. · `src/app/routes.py`
- [Services](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/services.py): Business logic · Attendance rules and NFC handling, including entry/exit decision logic. · `src/app/services.py`
- [Models](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/app/models.py): ORM schema · SQLAlchemy entities that map the attendance domain to database tables. · `src/app/models.py`
- **NFC input**: Device/simulated · Physical card scans or simulated UID input accepted by the system.

### Browser UI

Lightweight web interface served by the Flask app.

- [Web UI](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/front/index.html): Browser client · Embedded browser interface served from the backend for live visibility. · `src/front/index.html`

### Infrastructure

Containerized database and admin tooling.

- **MySQL**: Database · Persistent store for users, cards, rooms, and access records.
- **phpMyAdmin**: Admin UI · Containerized database administration interface.
- [Compose](https://github.com/dvleu/proyectoinvestigacion/blob/main/docker-compose.yml): Container stack · Defines the MySQL and phpMyAdmin runtime environment and persistence. · `docker-compose.yml`

### Database Assets

SQL schema and seed files for provisioning data.

- [Schema SQL](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/Schema/Schema.sql): DDL · Canonical database schema definition. · `src/Schema/Schema.sql`
- [Seed data](https://github.com/dvleu/proyectoinvestigacion/blob/main/src/Schema/seed.sql): Bootstrap data · Initial records for local setup or demo use. · `src/Schema/seed.sql`

## Connections

- App entry → Config: loads config · Bootstraps Flask and database settings.
- App entry → Routes: registers API · Wires HTTP endpoints into the server.
- App entry → Services: uses logic · Invokes attendance and NFC processing.
- App entry → Web UI: serves UI · Hosts the embedded web interface.
- Routes → Services: delegates · Routes call into business logic for attendance operations.
- Services → Models: queries/writes · Resolves cards and persists attendance records through ORM models.
- Models → MySQL: maps to · ORM entities correspond to the MySQL schema.
- NFC input → Services: UID scan · Physical or simulated card input enters the attendance flow.
- Web UI → Routes: fetches API · Browser UI consumes the same Flask endpoints.
- Compose → MySQL: provisions · Starts and persists the database container.
- Compose → phpMyAdmin: provisions · Starts the admin tooling container.
- Schema SQL → MySQL: defines schema · DDL used to create the attendance database structure.
- Seed data → MySQL: loads data · Initial seed records populate the database.
- Services → MySQL: attendance write · Creates access records after resolving the scanned UID.