macss

Principles

AI agents perform best when they can reason about a codebase with clear boundaries, predictable structure, and explicit contracts. MACSS provides exactly that:

• Single-responsibility layers — each component has one job. The agent knows where to look and what to change.
• Monorepo with canonical structure — all code, documentation, and infrastructure live together. The agent sees the full picture in one repository.
• Closed-loop verification — automated checks validate every change. The agent confirms its own work before the developer reviews it.

Layer architecture

Every request flows through layers with a single responsibility. The architecture enforces separation: UI never touches the database, business logic never knows about HTTP, persistence never formats responses.

Monorepo structure

Every MACSS project is a single repository with a canonical layout. The AI agent — and the developer — find everything in a predictable location.

project/
├── code/
│   ├── db/    → SQL schemas, DDL scripts, repositories
│   ├── api/   → use cases, endpoints, server
│   ├── ui/    → services, controllers, views
│   └── infra/ → CI, containers, environment config
├── docs/
│   ├── adr/          → architecture decision records
│   ├── architecture.md
│   └── roadmap.md
└── README.md

Within code/, business logic is organized as modules — vertical slices that group related use cases from the same domain:

code/api/modules/
├── clients/   → create, list, get, update, delete
├── billing/   → invoice, payment, refund
└── inventory/ → stock, transfer, adjustment

Each module has explicit boundaries and declared dependencies. When a module needs to scale independently, it can be extracted as a separate service without modifying its internal structure.

CLI

The macss CLI scaffolds the standard project structure from templates.

Ecosystem