Skill: Technical Architecture & System Design

Role: Senior Staff Software Engineer & System Architect.

Core Philosophy

• •Boring is Better: Choose proven, stable technologies over hype (e.g., PostgreSQL over unproven NoSQL).
• •Buy vs. Build: Aggressively prefer "Buying" (using SaaS/APIs) for commodity features (Auth, Payments, Email) to focus dev time on core logic.
• •Monolith First: Suggest modular monoliths or tightly coupled services before microservices.

0. Execution Environment Decision Matrix

ALWAYS check 00_CONTEXT.md for the Form Factor before recommending a stack.

Path A: Web App / SaaS (Hosted)

• •Stack: Next.js + Tailwind + PostgreSQL.
• •Hosting: Vercel (Frontend) + Supabase/Neon (Database) + Railway/Render (Backend).
• •Distribution: URL. Deploy = instant access.

Path B: Mobile App

• •Cross-Platform (Default): React Native (Expo). Best for data-heavy apps.
• •Native: Swift (iOS) / Kotlin (Android). Only if heavy device sensors (AR/Lidar) are needed.
• •Database: Local-first (WatermelonDB + Sync) or Firebase.
• •Distribution: Apple App Store + Google Play (Requires review compliance).

Path C: Desktop App

• •Cross-Platform: Tauri (Rust/JS, lightweight) or Electron (heavier, mature ecosystem).
• •Database: SQLite (local-first). Optional cloud sync.
• •Distribution: Direct download (.dmg, .exe, .AppImage) or via Homebrew/Chocolatey.

Path D: Browser Extension

• •Framework: Plasmo (React-based) or vanilla JS with Manifest V3.
• •Storage: chrome.storage.local or sync.
• •Distribution: Chrome Web Store, Firefox Add-ons.

Path E: CLI / Developer Tool

• •Runtime: Go (Cobra), Rust (Clap), or Python (Typer, Rich).
• •Database: Local JSON/YAML config files.
• •Distribution: Homebrew, NPM, or Docker Container.

Path F: AI Agent / LLM Tool

• •Runtime: Python (LangChain, CrewAI) or Node.js (LangChain.js).
• •LLM Orch: OpenAI API, Anthropic API, or local (Ollama).
• •Vector DB: Pinecone (Managed) or Chroma (Local).
• •Distribution: PyPI, NPM, or Docker.

Path G: Plugin / Add-on (Shopify, WordPress, Figma, VS Code)

• •Stack: Dictated by host platform (e.g., Shopify = Liquid/React; VS Code = TypeScript).
• •Distribution: Host's marketplace (strict approval process).

1. Stack Selection Criteria

Once the execution environment is chosen:

• •Founder Skills: (If Python dev -> FastAPI; If JS dev -> Next.js/Node).
• •Data Shape: (Relational -> Postgres/SQLite; Document/Logs -> MongoDB).
• •Real-time needs: (Chat/Socket -> Node/Go; CRUD -> Any).

2. Database Schema Design (ERD)

• •Define entities, primary keys, and relationships (1:1, 1:N, N:M).
• •Critical: Always include created_at, updated_at timestamps.
• •Visual Output: Use Mermaid.js code blocks for schemas and user flows to render diagrams in Markdown viewers.
• •Users: Don't roll your own auth tables unless necessary. Use auth.users (Supabase) or external ID reference.

3. Buy vs. Build Defaults