stack/docs/README.md

# 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](1-getting-started/1-quick-start/1-overview.md)** — Get up and running in 5 minutes
- **[Installation](1-getting-started/2-installation/)**
  - [Prerequisites](1-getting-started/2-installation/1-prerequisites.md)
  - [Local Setup](1-getting-started/2-installation/2-local-setup.md)
  - [Docker Setup](1-getting-started/2-installation/3-docker-setup.md)
- **[Configuration](1-getting-started/3-configuration/)**
  - [Environment Variables](1-getting-started/3-configuration/1-environment.md)
  - [Authentik OIDC](1-getting-started/3-configuration/2-authentik.md)

### 2. Development

Developer guides for contributing to Mosaic Stack.

- **[Workflow](2-development/1-workflow/)**
  - [Branching Strategy](2-development/1-workflow/1-branching.md)
  - [Testing Requirements](2-development/1-workflow/2-testing.md)
- **[Database](2-development/2-database/)**
  - Schema, migrations, and Prisma guides _(to be added)_
- **[Type Sharing](2-development/3-type-sharing/)**
  - [Type Sharing Strategy](2-development/3-type-sharing/1-strategy.md)

### 3. Architecture

Technical architecture and design decisions.

- **[Overview](3-architecture/1-overview/)** — System design _(to be added)_
- **[Authentication](3-architecture/2-authentication/)** — BetterAuth and OIDC _(to be added)_
- **[Design Principles](3-architecture/3-design-principles/)**
  - [PDA-Friendly Patterns](3-architecture/3-design-principles/1-pda-friendly.md)

### 4. API Reference

Complete API endpoint documentation.

- **[Conventions](4-api/1-conventions/)**
  - [Endpoint Conventions](4-api/1-conventions/1-endpoints.md)
- **[Authentication](4-api/2-authentication/)**
  - [Authentication Endpoints](4-api/2-authentication/1-endpoints.md)

## 📝 Scratchpads

Development notes and implementation details for specific issues:

- [Issue #1: Project Scaffold](scratchpads/1-project-scaffold.md)
- [Issue #2: PostgreSQL Schema](scratchpads/2-postgresql-pgvector-schema.md)
- [Issue #3: Prisma ORM Setup](scratchpads/3-prisma-orm-setup.md)
- [Issue #4: Authentik OIDC Integration](scratchpads/4-authentik-oidc-final-status.md)

## 🔍 Quick Links

### For New Users

1. [Quick Start](1-getting-started/1-quick-start/1-overview.md)
2. [Local Setup](1-getting-started/2-installation/2-local-setup.md)
3. [Environment Configuration](1-getting-started/3-configuration/1-environment.md)

### For Developers

1. [Branching Strategy](2-development/1-workflow/1-branching.md)
2. [Testing Requirements](2-development/1-workflow/2-testing.md)
3. [Type Sharing](2-development/3-type-sharing/1-strategy.md)

### For Architects

1. [PDA-Friendly Design](3-architecture/3-design-principles/1-pda-friendly.md)
2. [Authentication Flow](3-architecture/2-authentication/) _(to be added)_
3. [System Overview](3-architecture/1-overview/) _(to be added)_

### For API Consumers

1. [API Conventions](4-api/1-conventions/1-endpoints.md)
2. [Authentication Endpoints](4-api/2-authentication/1-endpoints.md)

## 📋 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](3-architecture/3-design-principles/1-pda-friendly.md)

### 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](https://git.mosaicstack.dev/mosaic/stack/issues/new)
- **Discussions:** [Project discussions](https://git.mosaicstack.dev/mosaic/stack/discussions)

---

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