stack/docs/3-architecture

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