Limitations & Future

Honest Assessment of Current State

This section provides radically honest analysis of The Architech CLI's current limitations and proposed upgrades.

Philosophy

We believe in transparent engineering. Every system has limitations — acknowledging them is the first step to improving them.

This documentation will:

• ✅ Be honest about current limitations
• ✅ Explain why they exist
• ✅ Propose concrete solutions
• ✅ Invite community contributions

Current Limitations

1. Type System Synchronization →

Issue: Types package can drift from CLI implementation.

Impact: Medium - Can cause TypeScript errors

Status: Needs solution

2. Sequential Execution Only →

Issue: Blueprints run one at a time, even if independent.

Impact: Low - Performance (but acceptable)

Status: Enhancement planned

3. No Partial Recovery →

Issue: Any blueprint failure aborts entire generation.

Impact: Medium - User must restart from scratch

Status: Checkpoint system proposed

4. Blueprint Validation at Runtime →

Issue: Invalid blueprints only caught when user runs them.

Impact: Low - Rare, but annoying when it happens

Status: Build-time validation proposed

Proposed Upgrades

1. Parallel Blueprint Execution →

Execute independent blueprints in parallel for 2-3x speed improvement.

Complexity: Medium
Benefit: High
Timeline: Q4 2024

2. Checkpoint & Resume System →

Save state after each blueprint, allow resuming from failures.

Complexity: High
Benefit: High
Timeline: Q1 2025

3. Auto-Generate Types from CLI →

Generate types package from CLI as single source of truth.

Complexity: Medium
Benefit: High (eliminates drift)
Timeline: Q4 2024

4. Build-Time Blueprint Validation →

Validate blueprint structure when marketplace is built, not at runtime.

Complexity: Low
Benefit: Medium
Timeline: Q4 2024

What Works Well (Don't Change)

✅ VFS Architecture

The per-blueprint VFS is a massive success:

• Zero corrupted projects
• Perfect blueprint isolation
• Clean error recovery

Decision: Keep as-is, don't change.

✅ AST-Based Modifications

ts-morph integration is rock solid:

• 95%+ success rate on complex TypeScript
• Handles edge cases reliably
• No reported AST corruption

Decision: Keep as-is, expand usage.

✅ Semantic Actions

High-level actions are beloved by blueprint authors:

• Simple API
• Consistent across marketplace
• Easy to learn

Decision: Keep as-is, add more actions.

Performance Characteristics

Current Performance

Genome execution time (SaaS Starter, 8 modules):

• Validation: ~50ms
• Dependency resolution: ~30ms
• Blueprint execution: ~2-5s
• npm install: ~20s (external)

Total: ~25-30s for complete project

Bottlenecks:

1. AST parsing (~200ms per file)
2. npm install (external, can't optimize)
3. Sequential execution (could parallelize)

Optimization Opportunities

1. Parallel Execution → 2-3x faster (independent blueprints)
2. Persistent AST Cache → Faster file modifications
3. Lazy VFS Pre-population → Only load when needed

Community Contributions Welcome

We invite community contributions for:

• 🎯 New modifiers for specific use cases
• 🎯 Performance optimizations
• 🎯 Additional blueprint actions
• 🎯 Testing and validation improvements

How to Contribute →

Roadmap

Q4 2024

• Type generation from CLI
• Parallel blueprint execution
• Build-time blueprint validation

Q1 2025

• Checkpoint & resume system
• Enhanced error messages
• Performance optimizations

Q2 2025

• Plugin system
• Custom action handlers
• Advanced caching strategies

We're transparent about limitations because we're confident in our solutions.

→ See Detailed Limitations →