Design Decisions
Architectural Choices & Their Rationale
This section explains why The Architech CLI is built the way it is. Every design decision involved trade-offs — this is where we explain them transparently.
Core Principles
All architectural decisions are guided by three principles:
1. Simplicity for the Creator
Complexity must be in the CLI, never in the blueprint.
Manifestation:
- Semantic actions instead of primitives
- Modifiers instead of direct AST manipulation
- High-level APIs
2. Security by Default
Never corrupt a user's project. Every operation must be safe and predictable.
Manifestation:
- Virtual File System (VFS)
- Atomic operations
- Fail-fast on errors
3. Open Extensibility
Architecture must encourage and facilitate community contribution.
Manifestation:
- Clear abstraction layers
- Documented APIs
- Plugin system (future)
Key Design Decisions
1. Per-Blueprint VFS Isolation →
Why each blueprint gets its own VFS instance.
Trade-off: Memory overhead vs safety and isolation
2. AST Not Regex →
Why we use ts-morph for file modifications.
Trade-off: Performance cost vs reliability
3. Dynamic Blueprint Functions →
Why blueprints can be functions that generate actions.
Trade-off: Complexity vs flexibility
4. Fail-Fast Execution →
Why we stop on first error instead of continuing.
Trade-off: Can't do "best effort" vs clearer UX
5. Sequential Execution →
Why blueprints run one at a time.
Trade-off: Slower vs simpler and safer
Reading Guide
Each decision page follows this structure:
- The Decision - What we chose
- Rationale - Why we chose it
- Alternatives Considered - What we didn't choose
- Trade-offs - Costs and benefits
- Future Considerations - Might we change it?
Understanding the "why" is as important as understanding the "what".