How lit-innosence/tus_yuurikai_system works
Project Type & Purpose
• Full-stack, containerized locker-rental application.
• Frontend: React/TypeScript SPA for users and admins.
• Backend: Rust API using Rocket + Diesel ORM on PostgreSQL.
• Purpose: secure locker reservations via system authentication and e-mail verification.
Main Components
a. Frontend SPA
• React app, built via npm scripts, served as static assets.
• Key modules:
• Routes & Pages (login, locker search, registration, admin pages)
• State management (Recoil) & API calls (axios, React Query)
• Auth component (OAuth with Outlook)
b. Backend API Service
• Rust Rocket server exposing REST/OpenAPI endpoints (utoipa).
• Layered into:
• Controller (HTTP models → use-cases)
• Use-case services (business logic)
• Domain entities (student, locker, assignment, auth)
• Adapters → repository interfaces for persistence
• Infrastructure/ORM layer (Diesel models, migrations)
c. Database
• PostgreSQL container
• Tables: student, student_pair, locker, assignment_record, auth, admin, locker_auth_info, circle_auth_info, etc.
d. External Services
• SMTP server (Lettre) for sending authentication emails.
• OAuth provider (Outlook API via reqwest for login).
• (Optional) reCAPTCHA verification via Google.
Relationships & Data Flow
• Browser → Frontend SPA
• User interactions trigger React Router navigation, form submissions.
• Frontend issues HTTPS requests (axios) to Rocket API.
• Frontend → Backend
• Authenticated calls include JWT (jsonwebtoken).
• File uploads/downloads handled via API.
• Backend layering:
• Controller layer receives HTTP, deserializes JSON (serde), forwards to use-cases.
• Use-case layer applies business rules, calls repository interfaces.
• Repository adapters translate calls into SQL via Diesel, return domain models.
• Domain layer handles invariants and aggregates.
• Infrastructure layer manages database schemas, Diesel connection pooling, migrations.
• Backend → Database
• Diesel executes SQL migrations, queries, and commands.
• Data persisted in Postgres volumes.
• Backend → External service
• Email dispatch via lettre SMTP.
• OAuth handshake via reqwest.
Architectural Patterns & Design Principles
• Hexagonal (Ports & Adapters) / Clean Architecture:
• Adapters directory for controllers and repositories.
• Domain and use-case separation ensures testability (see tests/ folder).
• Layered decomposition: HTTP → Controller → Use-case → Domain → Repository → DB.
• Containerization & isolation: Dockerfile for app, separate network for DB.
Essential Elements
• Clear labels: “React App”, “Rust Rocket API”, “PostgreSQL”
• Sub-component labels: “Controller Layer”, “Use-case Services”, “Diesel ORM”
• Data flows:
• Client → Frontend (HTTP UI)
• Frontend → API (HTTPS JSON)
• API → DB (SQL)
• API → SMTP (SMTP)
• API → OAuth (HTTPS REST)
• Blue for frontend, orange for backend, green for database, gray for external.