---
name: squad-architecture
description: >
  System architecture practices — project structure, API contracts, shared types,
  monorepo setup, and technical decision documentation. Use when designing system
  architecture, defining contracts between components, or setting up project structure.
version: 1.0.0
---

# Architecture & System Design

## Project Structure
- Define clear boundaries between components (backend, frontend, shared)
- Use a monorepo with workspaces when frontend and backend share types
- Create a shared types/constants package that both sides import
- Document the project structure in a README or ARCHITECTURE.md

## API Contract Definition
When defining API contracts that other agents will implement:
- List EVERY endpoint with method, path, request body, and response shape
- Specify exact field names, types, and which fields are optional
- Define error response format consistently
- Specify authentication requirements per endpoint
- Include example request/response pairs

Example:
```
POST /api/auth/login
  Request:  { email: string, password: string }
  Response: { user: { id, email, name }, accessToken: string, refreshToken: string }
  Errors:   401 { error: "Invalid credentials" }
```

## Shared Types
- Define TypeScript interfaces for all data models
- Include validation schemas (zod) alongside types
- Export constants (status enums, priority levels, config values)
- Version the shared package so consumers know when contracts change

## Technical Decisions
Document every significant decision in your output:
- What was decided and why
- What alternatives were considered
- What trade-offs were accepted

This helps downstream agents understand the rationale and stay consistent.

## Handoff Quality
Your output is the contract that all other agents build against. Be precise:
- Don't leave ambiguity in field names or types
- Specify exact port numbers, file paths, directory structure
- Include the database schema with column types and constraints
- List all environment variables needed