Core Service layer

The Core Service layer acts as the primary business logic engine within the ATMOS ecosystem. It is responsible for orchestrating complex operations, managing state across distributed components, and providing a unified interface for higher-level applications like the web frontend and landing pages to interact with the underlying system infrastructure.

This layer sits between the low-level infrastructure (such as database and terminal services) and the external-facing API layer. It ensures that business rules are consistently applied and that data integrity is maintained throughout the lifecycle of a request. For more information on how this fits into the broader system, see the Architecture Overview section.

Architecture and Design

The Core Service layer is built using a modular design that emphasizes the separation of concerns. It leverages Rust's type system to enforce safety and performance, providing a set of services that handle everything from workspace lifecycle management to authentication and authorization.

Layered Integration

The following diagram illustrates how the Core Service layer integrates with other parts of the ATMOS architecture:

Core Components and Modules

The service layer is organized into several key modules, each handling a specific domain of the application logic.

Service Initialization Flow

When the application starts, the Core Service layer undergoes an initialization process to wire up dependencies and prepare the execution environment.

Workspace Lifecycle Management

A primary responsibility of the Core Service is managing workspaces. This involves ensuring that each workspace is isolated and has the necessary resources to run terminal sessions and file operations.

Data Flow for Workspace Creation

The flow below describes how a request to create a new workspace is handled by the service layer:

Key Data Structures

The service layer utilizes several critical structs to maintain state and handle logic:

// Example structure representation based on service patterns
pub struct ServiceContext {
    pub db: Arc<DatabaseConnection>,
    pub config: Config,
    pub state: Arc<RwLock<GlobalState>>,
}

Sources: crates/core-service/src/lib.rs:1-50

AI Agent Instructions

The AGENTS.md file within the core service directory provides specific instructions for AI agents working within this layer. It emphasizes maintaining the "Deep Research" philosophy where agents must read entry points, core types, and implementations before proposing changes.

Key rules for contributors:

• Prose over code: Technical documentation should favor natural language and Mermaid diagrams.
• Trace the flow: Always document how a request moves from an API endpoint through the core service to storage.
• Error handling: Document failure modes and recovery strategies in prose.

Sources: crates/core-service/AGENTS.md

Summary

The Core Service layer is the "brain" of the ATMOS project, facilitating communication between the user-facing API and the low-level system infrastructure. By centralizing business logic, it provides a robust and scalable foundation for managing complex developer workflows, workspace isolation, and real-time terminal interactions.