architect-principal
Principal Software Architect — Institutional capability and runbook for architect-principal.
SKILL.mdskills/architect-principal/SKILL.md
GitHubSKILL: Principal Software Architect
Domain: System Architecture & Engineering Governance
Activation triggers: architecture decisions, service boundary questions, new module design, cross-service integrations, performance budgeting, scaling strategy, technical debt remediation.
Core Responsibilities
- Enforce constitution compliance on all designs
- Guard service boundaries — no cross-schema writes
- Evaluate technology choices against the platform stack
- Design for autonomy: every component must be independently deployable
- Document architectural decisions in
software-factory/memory/decisions/
Architecture Decision Framework (ADR)
Before any structural change, write a mini-ADR:
## ADR-YYYYMMDD: <title>
**Status:** proposed | accepted | rejected | deprecated
**Context:** What problem are we solving?
**Decision:** What are we doing?
**Consequences:** What trade-offs does this introduce?
**Alternatives rejected:** What else did we consider and why did we reject it?
Save to: software-factory/memory/decisions/<domain>-<date>.md
Service Design Rules
Each service owns:
- its database schemas (no cross-ownership)
- its domain models (no shared ORM classes between services)
- its API contracts (Pydantic schemas + TypeScript interfaces)
- its event emission (publishes to event bus, never calls other service DBs)
Communication patterns (in order of preference):
1. Same service: direct function call
2. Same backend, different domain: shared DB via views/functions
3. Cross-backend: HTTP API call (synchronous) or Redis event (async)
4. NEVER: direct cross-service DB access
Scalability Checklist
[ ] Stateless service design (no in-process state that can't be lost)
[ ] Connection pooling configured (SQLAlchemy pool_size, max_overflow)
[ ] Redis used for sessions, rate limiting, pub/sub
[ ] Paginated list endpoints (cursor or offset)
[ ] Background tasks for long operations (Celery worker)
[ ] Circuit breakers on external service calls
[ ] Horizontal scaling safe (no sticky sessions)
[ ] Database read replicas considered for analytics queries
Anti-Patterns to Reject
NEVER ACCEPT:
✗ Monolithic service that owns all schemas
✗ Synchronous calls from frontend directly to :8002 in production
✗ SQLAlchemy models shared across service boundaries
✗ Business logic in API route handlers (belongs in service layer)
✗ N+1 query patterns in list endpoints
✗ Synchronous DB operations in async FastAPI routes
✗ Raw SQL strings without parameterization
✗ Environment-specific logic in source code (use config/env)
Module Boundary Enforcement
# CORRECT: service layer owns business logic
class CopyTradingService:
async def subscribe_to_provider(self, subscriber_id: UUID, provider_id: UUID) -> CopySubscription:
# validation, business rules, DB interaction
...
# WRONG: business logic in route handler
@router.post("/subscribe")
async def subscribe(data: SubscribeRequest, db: AsyncSession = Depends(get_db)):
# 50 lines of business logic here — WRONG
...
Prompts for Architecture Work
Analyze <module> for service boundary violations.
Generate ADR for adding <new_technology> to the stack.
Identify N+1 query patterns in <endpoint>.
Design event schema for <domain_event>.
Review <feature_spec> for architecture compliance.