stack/docs

Mosaic Stack Documentation

Complete documentation for Mosaic Stack, organized in Bookstack-compatible shelf/book/chapter/page structure.

📚 Books

1. Getting Started

Essential guides to get Mosaic Stack installed and configured.

• Quick Start — Get up and running in 5 minutes
• Installation
  • Prerequisites
  • Local Setup
  • Docker Setup
• Configuration
  • Environment Variables
  • Authentik OIDC

2. Development

Developer guides for contributing to Mosaic Stack.

• Workflow
  • Branching Strategy
  • Testing Requirements
• Database
  • Schema, migrations, and Prisma guides (to be added)
• Type Sharing
  • Type Sharing Strategy

3. Architecture

Technical architecture and design decisions.

• Overview — System design (to be added)
• Authentication — BetterAuth and OIDC (to be added)
• Design Principles
  • PDA-Friendly Patterns

4. API Reference

Complete API endpoint documentation.

• Conventions
  • Endpoint Conventions
• Authentication
  • Authentication Endpoints

📝 Scratchpads

Development notes and implementation details for specific issues:

• Issue #1: Project Scaffold
• Issue #2: PostgreSQL Schema
• Issue #3: Prisma ORM Setup
• Issue #4: Authentik OIDC Integration

🔍 Quick Links

For New Users

1. Quick Start
2. Local Setup
3. Environment Configuration

For Developers

1. Branching Strategy
2. Testing Requirements
3. Type Sharing

For Architects

1. PDA-Friendly Design
2. Authentication Flow (to be added)
3. System Overview (to be added)

For API Consumers

1. API Conventions
2. Authentication Endpoints

📋 Documentation Standards

File Organization

docs/
├── {N}-{book-name}/              # Book (numbered)
│   ├── README.md                 # Book overview
│   ├── {N}-{chapter-name}/       # Chapter (numbered)
│   │   ├── {N}-{page-name}.md    # Page (numbered)
│   │   └── ...
│   └── ...
└── scratchpads/                  # Development notes (unnumbered)

Numbering Convention

• Books: 1-getting-started, 2-development, 3-architecture, 4-api
• Chapters: 1-quick-start, 2-installation, 3-configuration
• Pages: 1-overview.md, 2-local-setup.md, 3-docker-setup.md

Numbers maintain order in file systems and Bookstack.

Writing Style

• Concise — No unnecessary verbosity
• Action-oriented — Use imperative mood ("Run the command", not "You should run")
• Example-heavy — Show, don't just tell
• Code blocks — Always include working examples
• Links — Cross-reference related topics
• PDA-friendly — Follow design principles

Code Examples

Always include:

• Language identifier for syntax highlighting
• Complete, runnable examples
• Expected output when relevant
• Error cases and troubleshooting

🛠️ Contributing to Docs

Adding New Pages

1. Identify the appropriate book/chapter
2. Create numbered markdown file
3. Add to chapter's parent README
4. Link from related pages
5. Test all links and code examples

Updating Existing Pages

1. Keep formatting consistent
2. Update last-modified date
3. Test all examples
4. Check cross-references

Creating New Books

1. Number sequentially (5-{new-book})
2. Create README.md overview
3. Add chapter directories
4. Update this index

📊 Documentation Status

Book	Completion
Getting Started	🟢 Complete
Development	🟡 Partial
Architecture	🟡 Partial
API Reference	🟡 Partial

Legend:

• 🟢 Complete
• 🟡 Partial
• 🔵 Planned
• ⚪ Not started

🔗 External Resources

• Project Repository: https://git.mosaicstack.dev/mosaic/stack
• Issue Tracker: https://git.mosaicstack.dev/mosaic/stack/issues
• Google Style Guides: https://github.com/google/styleguide
• BetterAuth Docs: https://www.better-auth.com
• Prisma Docs: https://www.prisma.io/docs
• NestJS Docs: https://docs.nestjs.com

📧 Support

• Issues: Create an issue
• Discussions: Project discussions

---

Last Updated: 2026-01-28 Version: 0.0.1 (Pre-MVP)