Skip to content
OpenLogos

architecture-designer

Before diving into per-scenario technical implementation, establish the project’s technical global view — system architecture, technology selection, deployment topology, and non-functional constraints. Ensures that subsequent sequence diagrams, API designs, and code generation all proceed under consistent architectural constraints.

Phase & Trigger

Section titled “Phase & Trigger”
  • Phase: Phase 3 — HOW (Implementation), Step 0
  • Trigger conditions:
    • User requests technical architecture design or technology selection
    • User mentions “Phase 3 Step 0”, “architecture design”, “technical plan”
    • Phase 2 product design is complete

Prerequisites

Section titled “Prerequisites”
  • Requirements documents exist (logos/resources/prd/1-product-requirements/)
  • Product design documents exist (logos/resources/prd/2-product-design/)

What It Does

Section titled “What It Does”
  1. Read Phase 1/2 documents to understand the full product picture
  2. Recommend suitable system architecture based on product complexity
  3. Provide selection rationale and alternative comparisons for each technology choice
  4. Draw system architecture diagrams (Mermaid) and deployment topology diagrams
  5. Define non-functional constraints (performance, security, scalability)
  6. Catalog external dependencies and define test strategies for each
  7. Update tech_stack and external_dependencies in logos-project.yaml

Architecture by Complexity

Section titled “Architecture by Complexity”
ComplexityPatternExample
SimpleMonolith + single databasePersonal SaaS, utility products
MediumFrontend-backend separation + monolith backendTeam SaaS, multi-role systems
ComplexMicroservices / modular monolithHigh-concurrency, multi-platform

Technology Selection Format

Section titled “Technology Selection Format”

Each technology dimension includes a selection, rationale, and alternatives:

| Dimension | Selection | Rationale | Alternatives |
|-----------|-----------|-----------|-------------|
| Language | TypeScript | Unified frontend/backend, type safety | Go (when performance is priority) |
| Frontend | Next.js 15 | SSR + RSC, mature ecosystem | Astro (content sites) |
| Backend | Hono | Lightweight, edge-first, native TS | Express (ecosystem) |
| Database | PostgreSQL | Feature-rich, JSONB, RLS | MySQL (simple scenarios) |

External Dependencies & Test Strategies

Section titled “External Dependencies & Test Strategies”

All external service dependencies (email, payment, OAuth, etc.) must have test strategies defined at the architecture phase:

StrategyDescriptionTypical Scenario
test-apiTest environment provides a backdoor APIEmail/SMS verification codes
fixed-valueSpecific test data uses fixed valuesFixed verification code for test phones
env-disableEnvironment variable disables the featureCAPTCHA, slider verification
mock-callbackOrchestration calls a simulated callbackPayment callbacks, Webhooks
mock-serviceLocal mock service as replacementOAuth Provider

These strategies are written to external_dependencies in logos-project.yaml and consumed by the test-orchestrator Skill.

Outputs

Section titled “Outputs”
FileLocation
Architecture overviewlogos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md
Updated configlogos-project.yaml (tech_stack, external_dependencies)

Best Practices

Section titled “Best Practices”
  • Don’t over-engineer — for a solo developer, monolith + PostgreSQL + Vercel is sufficient
  • Selection rationale > selection itself — documenting “why” is more valuable than “what”
  • Architecture diagrams are prerequisites for sequence diagrams — system components become participants in subsequent diagrams
  • tech_stack is the AI’s anchor — subsequent AI code generation reads it from logos-project.yaml
  • Test strategies must be decided now — if deferred to orchestration testing, backdoor APIs are often missing
Section titled “Related Skills”