Architect is an AI-native software architecture language and compiler.
It describes domain models, services, APIs, event consumers, deployments, and versioned systems at a high level. The architecture becomes the source of truth, enabling deterministic code generation, refactoring, and long-term evolution of software systems.
Note
Architect is under active development. The parser, source loading, and project model resolution are already implemented. The code generation pipeline and execution engine are currently being finalized, with the first end-to-end implementation expected at the beginning of next week.
- Project Structure
- What Refers To What
- Project Definition
- Objects
- Common Types
- Services
- Applications
- Endpoints
- Consumers
- Workflow Actions
- Workflow Expressions
- Deployments
- Reference Summary
- Goal
A project contains one folder per version. Each version contains shared objects, services, and deployments.
Applications live inside services. Endpoints and consumers live inside applications.
stadan/
├── project.arch
│
├── 0.1.0/
│ ├── objects/
│ │ ├── User.arch
│ │ ├── Post.arch
│ │ ├── PostHistory.arch
│ │ └── PostEmbedding.arch
│ │
│ ├── services/
│ │ ├── maindb/
│ │ │ └── service.arch
│ │ └── blog_api/
│ │ ├── service.arch
│ │ └── application/
│ │ ├── application.arch
│ │ └── endpoints/
│ │ ├── CreatePost.arch
│ │ └── UpdatePost.arch
│ │
│ └── deployments/
│ ├── dev.arch
│ └── prod.arch
│
└── 0.1.1/
├── objects/
├── services/
└── deployments/
Architect uses references between files and declarations.
project.arch
└── references version folders and version files
version
├── references object files
├── references service files
└── references deployment files
service.arch
├── defines one runtime service
├── may reference one application file
├── may store object names
├── may declare event names
└── may explicitly depend on other services when no application is provided
application.arch
├── defines one application inside a service
├── references endpoint files
└── references consumer files
endpoint files
├── define HTTP API operations
├── use shared workflow actions
└── reference services by name when fetching, storing, emitting, or calling
consumer files
├── define event handlers
├── consume one event name
└── use shared workflow actions
deployment files
├── define one environment
├── reference service names
└── define runtime overrides for those services
The root project.arch file describes available versions and the files included in each version.
project Stadan {
version "0.1.0" {
services {
"services/maindb/service.arch"
"services/graphdb/service.arch"
"services/blog_api/service.arch"
}
objects {
"objects/User.arch"
"objects/Post.arch"
"objects/PostHistory.arch"
}
deployments {
"deployments/dev.arch"
"deployments/prod.arch"
}
next_version "0.1.1" {
services {
"services/maindb/service.arch"
}
deployments {
"deployments/prod.arch"
}
}
}
}
A project supports:
project ProjectName {
version "0.1.0" {
services {
"services/service_name/service.arch"
}
objects {
"objects/ObjectName.arch"
}
deployments {
"deployments/dev.arch"
}
next_version "0.1.1" {
services {
}
objects {
}
deployments {
}
}
}
}
Objects define shared domain models for a project version.
object User {
id UUID primary
email String unique
displayName String?
}
History objects are supported:
object PostHistory history_of Post {
id UUID primary
post Post
changedAt Time
}
Available field modifiers:
primary
unique
renamed_from PreviousFieldName
deprecated
Example:
object User {
id UUID primary
email String unique
fullName String renamed_from displayName
oldField String deprecated
}
Available object modifiers:
history_of ObjectName
renamed_from PreviousObjectName
deprecated
Example:
object PostHistory history_of Post {
id UUID primary
post Post
}
A type reference has this shape:
TypeName
TypeName?
TypeName+
TypeName*
TypeName[min,max]
TypeName[min,]
TypeName[,max]
List<TypeName>
List<TypeName>?
Examples:
id UUID
name String
displayName String?
age Int[0,120]
score Float[0,1]
tags List<String>
posts List<Post>?
Current literal value kinds:
string
int
float
bool
Examples:
name = "Steve"
count = 10
score = 0.98
enabled = true
Available number constraint kinds:
none
one_or_more
zero_or_more
range
Syntax:
Int+ // one_or_more
Int* // zero_or_more
Int[0,10] // range with min and max
Int[3,] // range with min only
Int[,100] // range with max only
A service describes a runtime node in the ecosystem.
Application-backed service:
service BlogAPI go {
exposes 8080
application "application/application.arch"
}
Infrastructure service:
service MainDB postgres {
version "17"
image "postgres:17"
exposes 5432
stores User
stores Post
stores PostHistory
}
Event bus service:
service Events hatchet {
version "latest"
event PostCreated
event PostUpdated
event PostScored
}
Available service kinds:
go
python
postgres
memgraph
milvus
hatchet
nginx
redis
prometheus
Available service properties:
version "..."
image "..."
exposes 8080
depends_on ServiceName
application "application/application.arch"
stores ObjectName
event EventName
Dependency rule:
If application is provided:
dependencies should be inferred from the application workflow.
If application is not provided:
dependencies should be declared explicitly using depends_on.
An application lives inside a service and references endpoints and/or consumers.
API application:
application BlogAPI {
emits rest on 8080
endpoints {
"endpoints/CreatePost.arch"
"endpoints/GetPost.arch"
}
consumers {
}
}
Worker application:
application DetectorWorker {
listens events on 9090
endpoints {
}
consumers {
"consumers/PostCreated.arch"
"consumers/PostUpdated.arch"
}
}
Port directions:
emits
listens
Port kinds:
rest
events
Application file blocks:
endpoints {
"endpoints/File.arch"
}
consumers {
"consumers/File.arch"
}
Endpoints define HTTP API behavior.
endpoint CreatePost POST "/posts" {
input {
title String body
content Text body
postedBy UUID body
}
create post:Post {
title = input.title
content = input.content
postedBy = input.postedBy
createdAt = now()
}
store post to MainDB
emit event:PostCreated {
post = post
}
return post
}
HTTP methods:
GET
POST
PUT
PATCH
DELETE
Input source kinds:
path
query
body
header
cookie
Input source rules:
id UUID path
id UUID body?
id UUID (path?|body?)
Meaning:
path required path input
body? optional body input
(path?|body?) exactly one of path or body may provide the value
Consumers react to one event.
consumes PostCreated {
fetch post:Post from MainDB where id == event.post.id
call EmbeddingService.Generate {
text = post.content
}
return post
}
A consumer contains workflow actions, just like endpoints.
Endpoints and consumers share the same workflow language.
Available actions:
fetch
create
store
update
emit
call
return
Fetches data from a service.
fetch post:Post from MainDB where id == input.id
References:
post local variable name
Post object/type name
MainDB service name
input.id endpoint input selector
Creates a new object or event value.
create post:Post {
title = input.title
content = input.content
}
Stores a variable into a service.
store post to MainDB
References:
post local variable
MainDB service name
Updates an existing variable.
update post {
title = input.title
updatedAt = now()
}
Emits an event.
emit event:PostCreated {
post = post
}
References:
event local event variable
PostCreated event type/name
Calls another service or function.
call EmbeddingService.Generate {
text = post.content
}
References:
EmbeddingService service name
Generate operation/function name
Returns a workflow expression.
return post
Available expression kinds:
identifier
selector
literal
function_call
Examples:
post
input.title
event.post.id
result.vector
now()
slugify(input.title)
calculateScore(input.title, 12, 12.5, true, false)
Special identifiers:
input endpoint input object
event consumed or emitted event object
result result from a previous call
Available comparators:
==
!=
<
<=
>
>=
Example:
fetch post:Post from MainDB where post.score >= 10
A deployment defines one runtime environment.
Development:
deployment dev {
vendor docker_compose
service BlogAPI {
replicas 1
}
service MainDB {
volume "main-db-data"
}
}
Production:
deployment prod {
vendor ansible
inventory "inventories/prod.ini"
service BlogAPI {
replicas 3
domain "api.stadan.org"
}
service MainDB {
host "prod-db-01"
volume "/var/lib/postgresql/data"
backup true
}
}
Available vendors:
docker_compose
ansible
kubernetes
Deployment-level properties:
vendor docker_compose
inventory "inventories/prod.ini"
Service deployment properties:
service ServiceName {
replicas 3
domain "api.example.com"
host "prod-db-01"
volume "/var/lib/postgresql/data"
backup true
}
backup supports:
true
false
Relationship overview:
Project
references Version definitions
Version
references Service files
references Object files
references Deployment files
Object
references other Object names through field types
Service
references Application file
references Object names through stores
references Event names through event
references other Service names through depends_on
Application
references Endpoint files
references Consumer files
Endpoint
references Object/type names
references Service names through fetch/store/call
emits Event names
Consumer
references one Event name
references Object/type names
references Service names through fetch/store/call
emits Event names
Deployment
references Service names
Architect aims to become the source of truth for software systems.
Instead of generating architecture from code, code is generated from architecture.
This enables:
deterministic code generation
AI-assisted development
automated refactoring
versioned evolution
infrastructure generation
deployment generation
long-term maintainability