Domain Model & Terminology

The platform uses a clear, consistent domain model. Each term maps to a distinct architectural concept.

Glossary

Term	Meaning
Console	Web platform (control plane)
alethia	CLI tool
Zone	Workspace / project grouping
Spec	A single infrastructure configuration
Runner	Execution agent (worker)
Apply	Deployment action (`alethia apply`)
Design	Create a new Spec configuration

Entity Relationships

User
 └── Zones (1:N)
      └── Specs (1:N)
           ├── Cloud Identity (N:1) ─── links to AWS/GCP/Azure account
           ├── spec_network (1:1) ─── VPC / VNet / VPC Network
           ├── spec_cluster (1:1) ─── EKS / GKE / AKS
           ├── spec_dns (1:1) ─── Route53 / Cloud DNS / Azure DNS
           ├── spec_repositories (1:1) ─── Git repo references
           ├── spec_databases (1:N) ─── Aurora / Cloud SQL / Azure DB
           ├── spec_caches (1:N) ─── ElastiCache / Memorystore / Azure Cache
           ├── spec_queues (1:N) ─── SQS / Pub/Sub / Service Bus
           ├── spec_topics (1:N) ─── SNS / Pub/Sub / Service Bus Topics
           ├── spec_nosql_tables (1:N) ─── DynamoDB / Firestore / Cosmos DB
           ├── spec_container_registries (1:N) ─── ECR / Artifact Registry / ACR
           ├── spec_secrets (1:N) ─── Secrets Manager / Secret Manager / Key Vault
           └── provision_jobs (1:N) ─── PLAN, DEPLOY, DESTROY, etc.
                └── provision_job_logs (1:N)

A Zone contains one or more Specs, and a Spec is provisioned by a Runner.

Singleton components (1:1 per Spec): network, cluster, DNS, repositories. Every Spec has exactly one of each (or none if that section is disabled).

Multi-instance components (1:N per Spec): databases, caches, queues, topics, NoSQL tables, container registries, secrets. A Spec can have zero or many of each.

Spec Lifecycle

A Spec progresses through these states:

DRAFT ──► QUEUED ──► PROVISIONING ──► ACTIVE
                                        │
                                        ▼
                                    DESTROYING ──► DESTROYED
                                        │
                                        ▼
                                      FAILED

Status	Meaning
`DRAFT`	Configuration created but not yet submitted for provisioning
`QUEUED`	A provisioning job has been created and is waiting for a Runner
`PROVISIONING`	A Runner is actively running Terraform
`ACTIVE`	Infrastructure is provisioned and running
`DESTROYING`	A destroy job is in progress
`DESTROYED`	Infrastructure has been torn down
`FAILED`	Provisioning or destruction failed (can be retried)

Component Status

Each Spec component (network, cluster, database, etc.) has its own status independent of the parent Spec:

Status	Meaning
`PENDING`	Awaiting first provisioning
`CREATING`	Currently being created by Terraform
`ACTIVE`	Successfully provisioned
`UPDATING`	Configuration change being applied
`FAILED`	Creation or update failed
`DESTROYING`	Being torn down
`DESTROYED`	Successfully removed

Job Lifecycle

Jobs represent units of work executed by Runners:

QUEUED ──► CLAIMED ──► PROCESSING ──► SUCCESS
                          │
                          ├──► FAILED
                          │
                          └──► CANCELLED

Status	Meaning
`QUEUED`	Waiting in the queue for a Runner to claim
`CLAIMED`	A Runner has atomically claimed this job
`PROCESSING`	Runner is actively executing (Terraform running)
`SUCCESS`	Job completed successfully
`FAILED`	Job failed (error message attached)
`CANCELLED`	User cancelled the job before completion

Job Types

Type	Purpose
`CONNECTION_TEST`	Verify cloud credentials work, cache discovered resources
`FETCH_RESOURCES`	Discover existing cloud resources (VPCs, subnets, hosted zones)
`BOOTSTRAP`	Initialize infrastructure workspace
`PLAN`	Run `terraform plan` + optional Infracost analysis
`DEPLOY`	Run `terraform apply` + install ArgoCD
`DESTROY`	Run `terraform destroy` with graceful cleanup
`DEPLOY_WORKER`	Provision Runner infrastructure (ECS task definition, IAM roles)
`DESTROY_WORKER`	Tear down Runner infrastructure

Environment Stages

Each Spec targets a specific environment:

Stage	Purpose
`development`	Development/testing infrastructure
`staging`	Pre-production validation
`production`	Production workloads

The environment stage affects naming conventions, resource sizing defaults, and Terraform state paths.

Domain Model & Terminology

On this page