> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Layered Architecture Design

> AiOS Interface / Usecase / Domain / Infrastructure layering, dependency rules, and runtime boundaries.

# Layered Architecture Design

## Audience

This page is for engineers implementing control-plane modules, installer flows, task orchestration, approval, and application delivery.

## Goal and Scope

This page defines the four-layer structure of the AiOS control plane, dependency direction, runtime boundaries, and how the “stateless services, externalized state” target is applied.

This page is the **code-dependency view**.
To understand runtime access, control, and execution topology, read it together with [Architecture](/en/platform/architecture), which serves as the **runtime topology view**.

## Core Concepts

### 1. Interface Layer

Includes:

* HTTP API
* CLI
* Agent CLI
* future progress/log streaming interfaces (SSE/WebSocket)

Responsibility: protocol translation, input parsing, error mapping, and invoking usecases.

### 2. Usecase Layer

Includes:

* install and bootstrap usecases
* deploy usecases
* database management usecases
* approval usecases
* task orchestration usecases

Responsibility: coordinate business flows without owning transport or infrastructure concerns.

### 3. Domain Layer

Includes:

* Project / Environment / App / Deployment
* Task / Approval / Audit
* DBInstance / DBAccessPolicy

Responsibility: domain models, constraints, and state semantics.

### 4. Infrastructure Layer

Includes:

* K3s/K8s adapters
* PostgreSQL / PgBouncer
* MinIO/S3
* Compose parsing and import implementations

Responsibility: integrate with external systems without redefining business semantics.

## Standard Workflow

### Dependency direction

Allowed direction:

`Interface -> Usecase -> Domain -> Infrastructure`

Forbidden:

* Interface depending directly on concrete infra implementations
* Infrastructure depending back on Interface
* modules reaching into each other’s internal subpackages freely

### Runtime boundary

* control-plane services are stateless replicas
* authoritative state lives in PostgreSQL / object storage
* in-process state is only allowed as bootstrap stubs or short-lived caches

## CLI Examples

```bash theme={null}
make test
make check-p0-contracts
```

## Web UI Path

* These architecture concepts are not direct navigation items, but they shape platform settings, task center, approval flows, and application delivery paths.

## Pitfalls / Risk Notes

* If a module needs to preserve business state, it must not rely on in-memory slices/maps as the authority.
* If an interaction must work across Web/CLI/Agent, it should live in the usecase/server contract instead of one specific channel.
* Some current skeleton implementations are temporary stubs and must not redefine the final production architecture.
* Do not misread this code-layer model as the runtime topology diagram; they are complementary views.

## Related Pages

* [Architecture](/en/platform/architecture)
* [Operations Overview](/en/operations/index)