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 /api prefix.
• 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:

1. Client Action: An admin interacts with admin-groups.js, which triggers an XMLHttpRequest.
2. API Entry: The request hits the api_server blueprint. The check_session_timeout middleware validates the user's session.
3. Business Logic: The specific API handler (e.g., saveAddGroup) validates the input data against configured limits.
4. Database Transaction: The db_engine opens a connection, executes the query with retry logic (to handle potential locks), and commits the change.
5. 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 bcrypt for 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).