Infrastructure & Database Layer
Relevant source files
The following files were used as context for generating this wiki page:
The Infrastructure & Database Layer serves as the foundational persistence and communication backbone of the ATMOS project. It abstracts low-level data access patterns and real-time communication protocols, providing a standardized interface for higher-level application logic to interact with the database and managed WebSocket sessions.
This layer is primarily housed within the crates/infra directory and is responsible for managing thread-safe database connection registries, implementing generic repository patterns for CRUD operations, and maintaining the lifecycle of real-time client connections.
Sources: crates/infra/AGENTS.md, crates/infra/src/db/connection.rs
Database Management & Connectivity
The database subsystem focuses on providing robust, thread-safe access to persistence storage. It utilizes a registry pattern to manage connections, ensuring that multiple parts of the application can safely share and access database resources without race conditions.
Connection Registry
The core of database connectivity is the DbRegistry, which acts as a thread-safe container for the database driver or connection pool. It is typically wrapped in an Arc (Atomic Reference Count) and utilizes an RwLock (Read-Write Lock) to allow concurrent read access while serializing administrative changes.
The use of Arc<RwLock<T>> allows the system to scale connection access across multiple asynchronous tasks efficiently.
Sources: crates/infra/src/db/connection.rs:1-15, skills/project-wiki/SKILL.md:Step 9
Repository Pattern
To decouple business logic from specific database implementation details, the infrastructure layer implements a Base Repository pattern. This provides a set of common operations that can be inherited or utilized by specific domain repositories.
| Operation | Description |
|---|---|
find_by_id | Retrieves a single entity based on its unique identifier. |
list | Returns a collection of entities, often supporting pagination or filtering. |
create | Persists a new entity to the database. |
update | Modifies an existing record based on provided changes. |
delete | Removes an entity from persistent storage. |
Sources: crates/infra/src/db/repo/base.rs:1-20
WebSocket Infrastructure
The infrastructure layer manages real-time bidirectional communication through a dedicated WebSocket subsystem. This system handles the complete lifecycle of a connection, from the initial HTTP upgrade to message routing and eventual disconnection.
Connection Lifecycle & Management
The WsManager is responsible for maintaining a registry of all active WebSocket connections. It tracks clients using unique identifiers and provides methods to broadcast messages or target specific sessions.
Data Structure for Real-time State
The state management within the WebSocket module relies on thread-safe collections to track active users and their respective communication channels.
| Component | Responsibility | Implementation Detail |
|---|---|---|
WsManager | Global connection registry | Arc<RwLock<HashMap<ClientId, WsConnection>>> |
WsConnection | Individual session state | Handles I/O and heartbeat monitoring |
ClientId | Unique session identifier | Used as key for lookups in the manager |
Sources: crates/infra/src/websocket/manager.rs, skills/project-wiki-update/references/output_structure.md
Technical Architecture Overview
The following diagram illustrates how the Infrastructure layer integrates with the broader system, acting as the mediator between the API layer and the underlying storage/network protocols.
Configuration & Setup
The infrastructure layer is initialized using environment-specific configurations. Key parameters include database connection strings, pool sizes, and WebSocket port settings. These are often validated during the application startup sequence to ensure the infrastructure is healthy before the API layer begins accepting traffic.
Sources: crates/infra/AGENTS.md, skills/project-wiki/SKILL.md:Step 3.2
Key Source Files
| File | Purpose |
|---|---|
crates/infra/src/db/connection.rs | Database connection registry and thread-safe access logic. |
crates/infra/src/db/repo/base.rs | Generic repository traits for standard CRUD operations. |
crates/infra/src/websocket/manager.rs | Central management of active WebSocket client sessions. |
crates/infra/src/websocket/connection.rs | Implementation of individual WebSocket session logic and I/O. |
crates/infra/AGENTS.md | High-level instructions for navigating and modifying the infra crate. |
The Infrastructure & Database Layer ensures that ATMOS maintains a clean separation between business logic and the complexities of persistence and real-time networking. By providing centralized registries and generic repository patterns, it allows the project to scale its data handling capabilities while maintaining thread safety and performance.