How dvleu/proyectoinvestigacion works
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: services.py Services · app.py App entry · routes.py Routes · docker-compose.yml Compose
Components 12
Flask App
Core Python application that serves the API and attendance workflow.
- App entry · Main executable that starts the server and orchestrates the attendance flow.
src/app/app.py - Config · Application and SQLAlchemy configuration, including database connection settings.
src/app/config.py - Routes · REST endpoints for users, cards, rooms, and access records.
src/app/routes.py - Services · Attendance rules and NFC handling, including entry/exit decision logic.
src/app/services.py - Models · SQLAlchemy entities that map the attendance domain to database tables.
src/app/models.py - NFC input · Physical card scans or simulated UID input accepted by the system.
Browser UI
Lightweight web interface served by the Flask app.
- Web UI · Embedded browser interface served from the backend for live visibility.
src/front/index.html
Infrastructure
Containerized database and admin tooling.
- MySQL · Persistent store for users, cards, rooms, and access records.
- phpMyAdmin · Containerized database administration interface.
- Compose · Defines the MySQL and phpMyAdmin runtime environment and persistence.
docker-compose.yml
Database Assets
SQL schema and seed files for provisioning data.
- Schema SQL · Canonical database schema definition.
src/Schema/Schema.sql - Seed data · Initial records for local setup or demo use.
src/Schema/seed.sql
Connections 14
- 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.