Semantic Surface
Architecture
A methodology for designing software systems using natural language naming that enables seamless human-AI collaboration.
What Is SSA?
Semantic Surface Architecture is a design methodology that prioritizes human-readable, evocative naming for every layer of a software system—from user interfaces to backend services to individual functions, errors, events, and states.
The core insight: When systems are named with meaningful words instead of technical jargon, both humans and AI can reason about them more effectively.
Instead of:
UserController → AuthService → validateCredentials() → AuthenticationException
SSA produces:
Gate.Verify.authenticate() → Gate.Verify.CredentialsInvalid
The vocabulary becomes the architecture. Every component has a semantic address that humans can speak and AI can navigate.
Why SSA Works
For Humans
- Memorable: "Vault" is easier to recall than "PaymentProcessingService"
- Intuitive: New team members understand the system in hours, not weeks
- Communicable: Stakeholders discuss architecture without translation
- Debuggable: Error reports become natural language descriptions
For AI
- Contextual: LLMs infer purpose from semantically rich names
- Navigable: AI assistants find relevant code by understanding intent
- Generatable: AI produces consistent code following naming patterns
- Traceable: AI follows event chains and state transitions by name alone
For Documentation
- Self-describing: Code reads like prose
- Searchable: Natural language names surface in searches
- Coherent: Single vocabulary across docs, code, tests, and conversation
The Five Layers
Surfaces
User-facing interfaces — the "windows" through which different actors view the system.
Examples: Market, Helm, Wire, Cortex, Guest, Core
Systems
Backend capabilities — bounded domains of functionality.
Examples: Gate, Vault, Prism, Orbit, Signal, Shield
Components
Operations within systems — named with nouns or gerunds.
Examples: Gate.Verify, Vault.Charge, Prism.Quote
Actions
Individual methods — named with verbs.
Examples: .authenticate(), .process(), .calculate()
Outcomes
Events, errors, and states — named with past-tense verbs or descriptive nouns.
Examples: .Completed, .Failed, .CredentialsInvalid
Surfaces Are Views, Not Instances
A critical distinction: Surfaces are perspectives into shared Systems, not separate copies.
┌─────────────────────────────────────────────────────────────────┐ │ SYSTEMS │ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ │ │ Gate │ │ Vault │ │ Forge │ │ Signal│ │ Lens │ │ │ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ │ │ │ │ │ │ │ │ │ └──────────┴────┬─────┴──────────┴──────────┘ │ │ │ │ │ ┌───────────────────┼───────────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ Guest │ │Market│ │ Core │ │ │ │ │ │ │ │ │ │ │ │Public│ │Buyer │ │Admin │ │ │ │ View │ │ View │ │ View │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ SURFACES │ └─────────────────────────────────────────────────────────────────┘
A Guest visitor and a Core admin both call the same underlying Systems—but the Surface determines visibility and permissions. The System provides the capability.
Naming Conventions
| Type | Convention | Example |
|---|---|---|
| Surfaces | PascalCase | Guest, Core, Market |
| Systems | PascalCase | Gate, Vault, Shelf |
| Components | PascalCase | Gate.Verify, Shelf.Content |
| Actions | camelCase | authenticate(), create() |
| Events | PascalCase | Session.Created |
| Errors | PascalCase | CredentialsInvalid |
| Files | kebab-case | guest-layout.astro |
| API Routes | kebab-case | /api/wire/gate/auth |
Core Principles
1. Names over abbreviations — "Vault" not "PaymentSvc"
2. Metaphors over descriptions — "Prism" not "PricingEngine"
3. Single words preferred — "Gate" not "AuthGateway"
4. Verbs for actions — authenticate() not doAuth()
5. Nouns for components — "Session" not "Managing"
6. Past tense for events — "Created" not "Create"
7. Hierarchy through dots — System.Component.action()
8. Consistency over creativity — Once named, stick with it
Get Started
Ready to apply SSA to your next project? Download the starter repo and begin building with semantic architecture from day one.