Files
stack/docs/3-architecture
Jason Woltje 403aba4cd3 docs: Add issue parser estimation strategy
Critical enhancement for real-world usage - parser must handle:
- Unformatted issues (estimate from content)
- Incomplete metadata (best-guess + confidence score)
- Oversized issues (auto-decompose before queuing)

Three-level estimation:
1. Structured metadata → extract directly (95%+ confidence)
2. Content analysis → AI estimates from description (50-95%)
3. Minimal info → defaults + warn user (<50%)

50% rule enforcement:
- Detect issues > 50% of agent's context limit
- Auto-decompose into sub-issues using Opus
- Create sub-issues in Gitea with dependencies
- Label parent as EPIC

Confidence-based workflow:
- ≥60%: Queue automatically
- 30-59%: Queue with warning
- <30%: Don't queue, request more details

Makes coordinator truly autonomous - handles whatever users throw at it.

Refs #158 (COORD-002)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 15:40:34 -06:00
..

Architecture

Technical architecture and design principles for Mosaic Stack.

Chapters

  1. Overview — System design and component architecture
  2. Authentication — BetterAuth integration and OIDC flow
  3. Design Principles — PDA-friendly patterns and UX guidelines

Architecture Principles

  • Type Safety First: Shared types prevent frontend/backend drift
  • Multi-Tenant Ready: Row-level security with workspace isolation
  • PDA-Friendly: Calm, stress-free language and visual design
  • Modular: Plugin architecture for extensibility

Technology Decisions

Key architectural choices and their rationale:

  • BetterAuth over Passport.js for modern authentication
  • Prisma ORM for type-safe database access
  • Monorepo with pnpm workspaces for code sharing
  • PostgreSQL + pgvector for AI-ready data storage

Next Steps

  • Review API for implementation details
  • Check Development for workflow standards