talos-access / docs /architecture.md
Greg
Claude Opus 4.7 (1M context)
Preparar despliegue en fly.io: monolito dockerizado + seeder demo
6aa6081
|
Raw History Blame Contribute Delete
2.1 kB
# Architecture β€” Talos Access
## System Overview
Talos Access is a multi-tenant school attendance management system with facial recognition, ID card design, and comprehensive role-based access control.
## Layers
### Frontend (React + TypeScript + Vite)
- **Routing:** React Router v6 with protected routes
- **State:** Zustand (auth store with localStorage persistence)
- **HTTP:** Axios instance with JWT token injection and 401 auto-redirect
- **UI:** Tailwind CSS with custom components
- **Card designer:** Fabric.js canvas
- **Facial:** Browser camera API with base64 image capture
### Backend (Python + FastAPI)
- **API:** RESTful, versioned (`/api/v1`)
- **Auth:** JWT (HS256, 60min expiry) with HTTPBearer
- **RBAC:** Role-based access control at endpoint level; permission system for granular access
- **DB:** MySQL 8+ via SQLAlchemy ORM
- **Migrations:** Alembic
- **Facial:** Face encoding comparison (Euclidean distance)
### Data Flow
1. Client authenticates β†’ receives JWT
2. JWT included in `Authorization: Bearer` header for all requests
3. `get_current_user` dependency decodes JWT and loads user from DB
4. RBAC middleware checks role/permissions
5. Multi-tenant isolation via `account_id` filter on all queries
## Key Patterns
- **Repository-less:** Endpoints query models directly (no service layer)
- **Dependency injection:** FastAPI `Depends()` for auth, DB sessions, plan gating
- **Pydantic schemas:** Request validation and response serialization
- **CSV bulk import:** Template download β†’ upload β†’ parse β†’ transaction commit
## Database Schema (Core Tables)
- `users` β€” Students, teachers, admins, representatives, administrativos, obreros
- `sections` β€” Class groups with `max_students` and `academic_period`
- `enrollments` β€” Student-to-section assignments (unique on section+student)
- `attendances` β€” Daily check-in/out records with `action` (in/out) and `note`
- `holidays` β€” Non-instructional days (national, school, vacation)
- `audit_log` β€” Action audit trail for compliance
- `section_schedules` β€” Weekly class scheduling grid