ASAASA Standard

Frequently Asked Questions

Frequently Asked Questions

Common questions about ASA

General Questions

What is ASA?

ASA (Atomic Slice Architecture) is an architectural standard for organizing AI-generated software. It defines rules for how code should be structured to remain maintainable when AI tools generate or modify it.

ASA is not a framework, library, or service. It's a design discipline — like REST for APIs or Twelve-Factor for cloud apps.

Is ASA just another framework?

No. ASA is a standard, not a framework.

A framework provides code you import and extend. ASA provides rules you follow when organizing code.

You can implement ASA in any language, with any framework. The ASA CLI (Python tool) is one specification, but ASA itself is language-agnostic.

Why not just use best practices?

Best practices assume human authorship and manual enforcement. They rely on discipline, code review, and developer experience.

ASA assumes:

  • AI generates 80% of new code
  • Developers may not review every line
  • Architecture must be enforced, not suggested

Best practices say "you should." ASA says "you must" — and provides tools to enforce it.

Does ASA work without AI?

Yes. ASA benefits any codebase, but it's designed specifically for AI-assisted development.

Without AI:

  • Slices provide clear feature boundaries
  • Contracts document intent explicitly
  • Linter catches architectural violations

With AI:

  • All of the above, plus safe regeneration
  • Bounded context for AI tools
  • Protection against AI-introduced coupling

Technical Questions

Is this just microservices?

No. Microservices are about deployment — separate processes, separate databases, network boundaries.

ASA is about code organization — how you structure a single application, regardless of deployment.

You can:

  • Build a monolith with ASA (one process, many slices)
  • Build microservices with ASA (one service = one or more slices)
  • Mix both (some slices in monolith, some as services)

ASA is orthogonal to deployment strategy.

Isn't duplication bad? What about DRY?

DRY (Don't Repeat Yourself) remains valuable — but requires nuance in AI-generated systems.

The key question: If you change this logic, should it change everywhere or only in this slice?

Share when:

  • Logic is identical across slices and should stay synchronized
  • It's infrastructure (database, logging, config)
  • It's a constant or pure utility function

Duplicate when:

  • Logic may differ per slice in the future
  • It's business logic specific to one feature's context
  • Coupling would create hidden dependencies

ASA says: Share identical logic. Duplicate context-specific logic.

Example:

# ✅ SHARE: Password validation (identical everywhere, change once = change all)
# shared/validators.py
MIN_PASSWORD_LENGTH = 12

def validate_password(password: str) -> bool:
    return len(password) >= MIN_PASSWORD_LENGTH

# ✅ SHARE: Infrastructure
# shared/database.py
def get_session():
    return SessionLocal()

# ✅ DUPLICATE: Slice-specific validation (may differ per feature)
# domains/auth/register/service.py
def _validate_registration(data: dict) -> bool:
    # Registration has specific rules (e.g., requires terms acceptance)
    return data.get("terms_accepted") and validate_password(data["password"])

# domains/auth/reset_password/service.py
def _validate_reset(data: dict) -> bool:
    # Reset has different rules (e.g., requires token)
    return data.get("token") and validate_password(data["password"])

Rule of thumb: If you'd want a linter to warn you when slices diverge, share it. If divergence is expected, duplicate it.

Does ASA limit flexibility?

ASA limits chaos, not flexibility.

You can still:

  • Choose any tech stack
  • Implement any business logic
  • Use any external libraries
  • Deploy anywhere

What you cannot do:

  • Create hidden dependencies between slices
  • Import from other domains
  • Skip the spec → contract → implementation flow

These constraints prevent the flexibility that leads to unmaintainable code.

What about performance?

ASA's boundaries have zero runtime overhead. They're organizational, not technical.

At runtime:

  • Slices are just Python modules
  • Contracts are not loaded
  • No extra layers or abstractions

The linter runs at development time, not in production.

Can I use ASA with existing code?

Yes. ASA is designed for incremental adoption.

Strategy:

  1. Use ASA for all new features
  2. When you modify existing code, refactor it into a slice
  3. Over time, the codebase becomes ASA-compliant

You don't need a big-bang migration.

Workflow Questions

Do I need to write specs for everything?

Yes, for every slice. The spec is the source of truth.

But specs are fast to write:

  • 7 required sections
  • Markdown format
  • 10-20 lines for simple features
  • 50-100 lines for complex features

Writing a spec takes 5-15 minutes. It saves hours of debugging later.

What if I need to change a spec after implementation?

Change the spec, regenerate the contract, regenerate the skeleton. Your implementation code (between markers) is preserved.

# 1. Edit spec
vim domains/auth/login/slice.spec.md

# 2. Regenerate contract
asa generate-contract auth/login

# 3. Regenerate skeleton (preserves your code)
asa regenerate-slice auth/login

Your business logic survives. The structure updates.

Can I skip the contract and write code directly?

Technically yes, but you lose ASA's benefits:

  • No deterministic regeneration
  • No linter validation
  • No machine-readable interface
  • No documentation for future developers

The contract takes 2 seconds to generate. Don't skip it.

What if two slices need to share logic?

Ask: If I change this logic, should it change in both slices automatically?

If YES → Share it in shared/:

# shared/validators.py
def validate_email(email: str) -> bool:
    return "@" in email and "." in email.split("@")[1]

# shared/email_sender.py
def send_email(to: str, subject: str, body: str):
    # Implementation
    pass

If NO (or MAYBE) → Duplicate it in each slice:

# domains/auth/register/service.py
def _validate_registration_email(email: str) -> bool:
    # Registration might add domain whitelist later
    return "@" in email and "." in email.split("@")[1]

# domains/auth/login/service.py  
def _validate_login_email(email: str) -> bool:
    # Login might allow legacy formats later
    return "@" in email and "." in email.split("@")[1]

Guidelines:

  • Constants and pure utilities → shared/
  • Infrastructure (database, logging, HTTP clients) → shared/
  • Feature-specific logic that may diverge → duplicate
  • When in doubt, start in shared/ and extract to slice if it diverges

How do slices communicate?

Slices do not communicate directly. They're isolated.

If Slice A needs data from Slice B:

  1. Slice A calls Slice B's public API (via HTTP or function call)
  2. Slice B returns data via its contract
  3. No direct imports between slices

For synchronous in-process communication:

# domains/auth/login/service.py
from domains.auth.get_user.service import GetUserService

# This is allowed if both slices are in the same domain
# But prefer explicit contracts over direct calls

For asynchronous communication:

  • Use message queues
  • Use events
  • Use shared database (read-only)

Tooling Questions

Do I need the ASA CLI?

No. ASA is a standard. The CLI is one implementation.

You can:

  • Follow ASA rules manually
  • Build your own generator
  • Use a different tool that implements ASA

The CLI makes it easier, but it's not required.

What languages does ASA support?

The ASA standard is language-agnostic.

The specification currently targets Python (FastAPI + Pydantic). The standard can be implemented for other languages and frameworks. Community implementations may follow.

Can I use ASA with [my framework]?

ASA works with any framework that supports modular code organization and explicit type systems.

The specification targets Python (FastAPI + Pydantic). The architectural principles (slice isolation, boundary enforcement, deterministic regeneration) are applicable to any stack.

Does ASA work with monorepos?

Yes. ASA is ideal for monorepos.

Structure:

monorepo/
├── backend/
│   └── domains/
│       ├── auth/
│       └── billing/
├── frontend/
│   └── domains/
│       ├── auth/
│       └── billing/
└── shared/
    ├── types/
    └── utils/

Each domain can be a separate package, but they all follow ASA rules.

Adoption Questions

How long does it take to learn ASA?

  • Read documentation: 1-2 hours
  • Create first slice: 30 minutes
  • Comfortable with workflow: 1-2 days
  • Internalize principles: 1-2 weeks

ASA is simple by design. The learning curve is shallow.

What's the migration path for existing projects?

Phase 1: New features only (Week 1)

  • Use ASA for all new features
  • Leave existing code unchanged

Phase 2: Refactor on touch (Months 1-3)

  • When you modify existing code, refactor it into a slice
  • Gradually increase ASA coverage

Phase 3: Full compliance (Months 3-6)

  • All active code follows ASA
  • Legacy code remains until it needs changes

No big-bang rewrite required.

Can I hire developers who know ASA?

ASA is new, so few developers have direct experience.

But any developer who understands:

  • Vertical slice architecture
  • Domain-driven design
  • Dependency inversion

Can learn ASA in a few hours.

The concepts are familiar. The enforcement is new.

Is there commercial support?

ASA is a public standard. No vendor owns it.

For support:

Commercial consulting may be available from independent developers who implement ASA.

Comparison Questions

ASA vs Clean Architecture?

Clean Architecture (Uncle Bob) defines layers: Entities, Use Cases, Interface Adapters, Frameworks.

ASA defines vertical slices that cut across layers.

You can combine them:

  • Use Clean Architecture principles within each slice
  • Use ASA to organize slices

They're complementary, not competing.

ASA vs Domain-Driven Design?

DDD defines domains, bounded contexts, aggregates, entities, value objects.

ASA is a practical implementation of bounded contexts for AI-generated code.

ASA borrows from DDD:

  • Domains map to DDD domains
  • Slices map to DDD bounded contexts
  • Contracts map to DDD published language

ASA is "DDD for AI-assisted development."

ASA vs Vertical Slice Architecture?

Vertical Slice Architecture (Jimmy Bogard) organizes code by feature, not by layer.

ASA is vertical slice architecture with:

  • Explicit contracts
  • Deterministic regeneration
  • Boundary enforcement via linter
  • Designed for AI tools

ASA is "Vertical Slices + AI Safety."

ASA vs Modular Monolith?

Modular Monolith is a deployment pattern — one process, multiple modules.

ASA is a code organization pattern — how you structure those modules.

You can build a modular monolith using ASA. ASA defines how modules (slices) are structured and how they interact.

Philosophical Questions

Why does ASA exist?

AI tools generate code fast, but without architectural constraints, they create unmaintainable systems.

Existing patterns (MVC, Clean Architecture, DDD) assume human authorship. They rely on discipline and code review.

ASA assumes AI authorship. It provides enforceable rules that prevent AI from creating chaos.

Who maintains ASA?

ASA is a public standard. Currently maintained by the original authors.

Long-term vision:

  • Community governance
  • RFC-style evolution
  • Independent implementations

ASA is designed to outlive any single vendor or tool.

Will ASA become obsolete when AI improves?

No. Better AI makes ASA more valuable, not less.

As AI becomes more capable:

  • It generates more code
  • Architectural constraints become more critical
  • The cost of chaos increases

ASA is not a workaround for bad AI. It's a safety mechanism for powerful AI.

Can I modify ASA for my needs?

ASA is a standard, not a law. You can:

  • Adapt it to your context
  • Add domain-specific rules
  • Use a subset of features

But if you deviate significantly, you lose:

  • Compatibility with ASA tools
  • Ability to hire ASA-familiar developers
  • Community support

Prefer extending ASA over forking it.

Getting Started

Where do I start?

  1. Read the Manifesto — Understand the "why"
  2. Review Core Principles — Understand the "what"
  3. See How ASA Works — Understand the "how"
  4. Explore the Standard — Specification
  5. Apply to one new feature — Learn by doing

Start small. Build confidence. Scale gradually.

What if I have more questions?

ASA is designed to be self-explanatory. If something is unclear, that's a documentation bug. Please report it.

ASA v1.0.2 — An open standard for AI-generated software architecture.

No vendor. No license. No cost.