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