System Architecture
Atslegas is built on a modular, multi-tier architecture designed for reliability and clear separation of concerns. The system leverages the Flask Blueprint pattern to decouple the backend business logic from the frontend presentation layers.
System Overview
The application is divided into three primary layers: the Client-Side Frontends, the RESTful API, and the Database Engine. This separation ensures that the user interface remains responsive while the backend handles complex state management and security.
1. Dual-Interface Frontend
The frontend is split into two distinct environments to accommodate different user roles:
- User Interface (
/): A streamlined dashboard for general staff and students to view key availability and current status. - Admin Dashboard (
/admin): A comprehensive management suite for administrators to control users, groups, key inventories, and system logs.
Both interfaces are built as modern, client-side applications that communicate with the backend exclusively via asynchronous JSON requests (AJAX).
2. Modular Backend API
The core business logic resides in the api_server.py blueprint. This layer acts as the orchestrator for the system:
- Request Routing: Handles all programmatic interactions under the
/apiprefix. - Authentication & RBAC: Enforces Role-Based Access Control, ensuring that only users with proper permissions (e.g.,
admin,root) can access sensitive management endpoints. - Session Guard: Implements a server-side session validator that checks for activity timeouts and clears stale credentials to maintain system security.
3. Database Engine & Persistence
Atslegas uses a robust SQLite backend managed by a custom db_engine. Key architectural choices include:
- Write-Ahead Logging (WAL): Enabled to allow multiple readers and a single writer to operate simultaneously without locking the database, crucial for multi-user environments.
- Connection Lifecycle: Database connections are managed on a per-request basis. They are opened when a request starts and automatically closed/teared down when the request finishes, preventing resource leaks.
- ORM-like Helpers: The system uses structured classes (e.g.,
User,UserData,KeyGroup) to abstract raw SQL into manageable methods.
Data Flow
The following sequence illustrates how a typical action (like updating a key's status) moves through the architecture:
- Client Action: An admin interacts with
admin-groups.js, which triggers anXMLHttpRequest. - API Entry: The request hits the
api_serverblueprint. Thecheck_session_timeoutmiddleware validates the user's session. - Business Logic: The specific API handler (e.g.,
saveAddGroup) validates the input data against configured limits. - Database Transaction: The
db_engineopens a connection, executes the query with retry logic (to handle potential locks), and commits the change. - JSON Response: The API returns a success or error status to the frontend, which updates the UI dynamically.
Security & Session Management
Architecture-level security is handled via server-side filesystem sessions. Unlike standard cookie-based sessions, Atslegas stores session data on the server's disk within the flask_session/ directory.
- Revocation: Administrators can effectively log out users by clearing the session storage.
- Timeout Control: Session lifetimes are configurable via
config.json, and the backend strictly enforces these limits regardless of client-side state. - Password Security: The system uses
bcryptfor hashing and salting passwords before they ever reach the persistence layer.
Configuration & Environment
The architecture is driven by a config.json file. This allows the system to be deployed in different environments (Development vs. Production) without modifying the source code. It controls:
- Database file paths and schema locations.
- Session storage directories and timeout intervals.
- Input validation limits (username/password lengths).