docs: Restructure documentation with Bookstack-compatible hierarchy
- Organized docs into numbered shelf/book/chapter/page structure - Created comprehensive README.md with project overview - Added Getting Started book (quick start, installation, configuration) - Added Development book (workflow, testing, type sharing) - Added Architecture book (design principles, PDA-friendly patterns) - Added API Reference book (conventions, authentication) - Moved TYPE-SHARING.md to proper location - Updated all cross-references in main README - Created docs/README.md as master index - Removed old QA automation reports - Removed deprecated SETUP.md (content split into new structure) Documentation structure follows Bookstack best practices: - Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api - Numbered chapters and pages for ordering - Clear hierarchy and navigation - Cross-referenced throughout Complete documentation available at: docs/README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
378
README.md
Normal file
378
README.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# Mosaic Stack
|
||||
|
||||
Multi-tenant personal assistant platform with PostgreSQL backend, Authentik SSO, and MoltBot integration.
|
||||
|
||||
## Overview
|
||||
|
||||
Mosaic Stack is a modern, PDA-friendly platform designed to help users manage their personal and professional lives with:
|
||||
|
||||
- **Multi-user workspaces** with team collaboration
|
||||
- **Task management** with flexible organization
|
||||
- **Event & calendar** integration
|
||||
- **Project tracking** with Gantt charts and Kanban boards
|
||||
- **MoltBot integration** for natural language interactions
|
||||
- **Authentik OIDC** for secure, enterprise-grade authentication
|
||||
|
||||
**Version:** 0.0.1 (Pre-MVP)
|
||||
**Repository:** https://git.mosaicstack.dev/mosaic/stack
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Frontend** | Next.js 16 + React + TailwindCSS + Shadcn/ui |
|
||||
| **Backend** | NestJS + Prisma ORM |
|
||||
| **Database** | PostgreSQL 17 + pgvector |
|
||||
| **Cache** | Valkey (Redis-compatible) |
|
||||
| **Auth** | Authentik (OIDC) via BetterAuth |
|
||||
| **AI** | Ollama (local or remote) |
|
||||
| **Messaging** | MoltBot (stock + plugins) |
|
||||
| **Real-time** | WebSockets (Socket.io) |
|
||||
| **Monorepo** | pnpm workspaces + TurboRepo |
|
||||
| **Testing** | Vitest + Playwright |
|
||||
| **Deployment** | Docker + docker-compose |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+ and pnpm 9+
|
||||
- PostgreSQL 17+ (or use Docker)
|
||||
- Docker & Docker Compose (optional, for turnkey deployment)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
|
||||
cd mosaic-stack
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Configure environment variables (see CONFIGURATION.md)
|
||||
# Edit .env with your database and auth settings
|
||||
|
||||
# Generate Prisma client
|
||||
pnpm prisma:generate
|
||||
|
||||
# Run database migrations
|
||||
pnpm prisma:migrate
|
||||
|
||||
# Seed development data (optional)
|
||||
pnpm prisma:seed
|
||||
|
||||
# Start development servers
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Docker Deployment (Turnkey)
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
|
||||
# Stop services
|
||||
docker compose down
|
||||
```
|
||||
|
||||
See [Installation Guide](docs/1-getting-started/2-installation/) for detailed installation instructions.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
mosaic-stack/
|
||||
├── apps/
|
||||
│ ├── api/ # NestJS backend API
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── auth/ # BetterAuth + Authentik OIDC
|
||||
│ │ │ ├── prisma/ # Database service
|
||||
│ │ │ └── app.module.ts # Main application module
|
||||
│ │ ├── prisma/
|
||||
│ │ │ └── schema.prisma # Database schema
|
||||
│ │ └── Dockerfile
|
||||
│ └── web/ # Next.js 16 frontend (planned)
|
||||
│ ├── app/
|
||||
│ ├── components/
|
||||
│ └── Dockerfile
|
||||
├── packages/
|
||||
│ ├── shared/ # Shared types & utilities
|
||||
│ │ └── src/types/
|
||||
│ │ ├── auth.types.ts # Auth types (AuthUser, Session, etc.)
|
||||
│ │ ├── database.types.ts # DB entity types
|
||||
│ │ └── enums.ts # Shared enums
|
||||
│ ├── ui/ # Shared UI components (planned)
|
||||
│ └── config/ # Shared configuration (planned)
|
||||
├── plugins/ # MoltBot skills (planned)
|
||||
│ ├── mosaic-plugin-brain/ # API query skill
|
||||
│ ├── mosaic-plugin-calendar/ # Calendar skill
|
||||
│ └── mosaic-plugin-tasks/ # Task management skill
|
||||
├── docker/
|
||||
│ ├── docker-compose.yml # Production deployment
|
||||
│ └── init-scripts/ # PostgreSQL initialization
|
||||
├── docs/
|
||||
│ ├── SETUP.md # Installation guide
|
||||
│ ├── CONFIGURATION.md # Environment configuration
|
||||
│ ├── DESIGN-PRINCIPLES.md # PDA-friendly design patterns
|
||||
│ ├── API.md # API documentation
|
||||
│ ├── TYPE-SHARING.md # Type sharing strategy
|
||||
│ └── scratchpads/ # Development notes
|
||||
├── .env.example # Environment template
|
||||
├── turbo.json # TurboRepo configuration
|
||||
└── pnpm-workspace.yaml # Workspace configuration
|
||||
```
|
||||
|
||||
## Current Implementation Status
|
||||
|
||||
### ✅ Completed (v0.0.1)
|
||||
|
||||
- **Issue #1:** Project scaffold and monorepo setup
|
||||
- **Issue #2:** PostgreSQL 17 + pgvector database schema
|
||||
- **Issue #3:** Prisma ORM integration with tests and seed data
|
||||
- **Issue #4:** Authentik OIDC authentication with BetterAuth
|
||||
|
||||
**Test Coverage:** 26/26 tests passing (100%)
|
||||
|
||||
### 🚧 In Progress (v0.0.x)
|
||||
|
||||
- **Issue #5:** Multi-tenant workspace isolation (planned)
|
||||
- **Issue #6:** Frontend authentication UI (planned)
|
||||
- **Issue #7:** Task management API & UI (planned)
|
||||
|
||||
### 📋 Planned Features (v0.1.0 MVP)
|
||||
|
||||
- Event/calendar management
|
||||
- Project tracking with Gantt charts
|
||||
- MoltBot integration
|
||||
- WebSocket real-time updates
|
||||
- Data migration from jarvis-brain
|
||||
|
||||
See the [issue tracker](https://git.mosaicstack.dev/mosaic/stack/issues) for complete roadmap.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
- `main` — Stable releases only
|
||||
- `develop` — Active development (default working branch)
|
||||
- `feature/*` — Feature branches from develop
|
||||
- `fix/*` — Bug fix branches
|
||||
|
||||
### Running Locally
|
||||
|
||||
```bash
|
||||
# Start all services (requires Docker for PostgreSQL)
|
||||
pnpm dev # All apps
|
||||
|
||||
# Or run individually
|
||||
pnpm dev:api # API only (http://localhost:3001)
|
||||
pnpm dev:web # Web only (http://localhost:3000)
|
||||
|
||||
# Database tools
|
||||
pnpm prisma:studio # Open Prisma Studio
|
||||
pnpm prisma:migrate # Run migrations
|
||||
pnpm prisma:generate # Regenerate Prisma client
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
pnpm test # All tests
|
||||
pnpm test:api # API tests only
|
||||
pnpm test:web # Web tests only
|
||||
pnpm test:e2e # E2E tests with Playwright
|
||||
pnpm test:coverage # Generate coverage report
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
pnpm build # Build all apps
|
||||
pnpm build:api # Build API only
|
||||
pnpm build:web # Build web only
|
||||
```
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Mosaic Stack follows strict **PDA-friendly design principles**:
|
||||
|
||||
### Language Guidelines
|
||||
|
||||
We **never** use demanding or stressful language:
|
||||
|
||||
| ❌ NEVER | ✅ ALWAYS |
|
||||
|----------|-----------|
|
||||
| OVERDUE | Target passed |
|
||||
| URGENT | Approaching target |
|
||||
| MUST DO | Scheduled for |
|
||||
| CRITICAL | High priority |
|
||||
| YOU NEED TO | Consider / Option to |
|
||||
| REQUIRED | Recommended |
|
||||
|
||||
### Visual Principles
|
||||
|
||||
- **10-second scannability** — Key info visible immediately
|
||||
- **Visual chunking** — Clear sections with headers
|
||||
- **Single-line items** — Compact, scannable lists
|
||||
- **Calm colors** — No aggressive reds for status indicators
|
||||
- **Progressive disclosure** — Details on click, not upfront
|
||||
|
||||
See [Design Principles](docs/3-architecture/3-design-principles/1-pda-friendly.md) for complete guidelines.
|
||||
|
||||
## API Conventions
|
||||
|
||||
### Endpoints
|
||||
|
||||
```
|
||||
GET /api/{resource} # List (with pagination, filters)
|
||||
GET /api/{resource}/:id # Get single item
|
||||
POST /api/{resource} # Create new item
|
||||
PATCH /api/{resource}/:id # Update item
|
||||
DELETE /api/{resource}/:id # Delete item
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
All authenticated endpoints require a Bearer token:
|
||||
|
||||
```http
|
||||
Authorization: Bearer {session_token}
|
||||
```
|
||||
|
||||
See [API Reference](docs/4-api/) for complete API documentation.
|
||||
|
||||
## Configuration
|
||||
|
||||
Key environment variables:
|
||||
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://mosaic:password@localhost:5432/mosaic
|
||||
|
||||
# Authentik OIDC
|
||||
OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
|
||||
OIDC_CLIENT_ID=your-client-id
|
||||
OIDC_CLIENT_SECRET=your-client-secret
|
||||
|
||||
# JWT Session
|
||||
JWT_SECRET=change-this-to-a-random-secret-in-production
|
||||
JWT_EXPIRATION=24h
|
||||
|
||||
# Application
|
||||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
See [Configuration](docs/1-getting-started/3-configuration/1-environment.md) for all configuration options.
|
||||
|
||||
## Type Sharing
|
||||
|
||||
Types used by both frontend and backend live in `@mosaic/shared`:
|
||||
|
||||
```typescript
|
||||
import type { AuthUser, Task, Event } from "@mosaic/shared";
|
||||
|
||||
// Frontend
|
||||
function UserProfile({ user }: { user: AuthUser }) {
|
||||
return <div>{user.name}</div>;
|
||||
}
|
||||
|
||||
// Backend
|
||||
@Get("profile")
|
||||
@UseGuards(AuthGuard)
|
||||
getProfile(@CurrentUser() user: AuthUser) {
|
||||
return user;
|
||||
}
|
||||
```
|
||||
|
||||
See [Type Sharing Strategy](docs/2-development/3-type-sharing/1-strategy.md) for the complete type sharing strategy.
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Check the [issue tracker](https://git.mosaicstack.dev/mosaic/stack/issues) for open issues
|
||||
2. Create a feature branch: `git checkout -b feature/my-feature develop`
|
||||
3. Make your changes with tests (minimum 85% coverage required)
|
||||
4. Run tests: `pnpm test`
|
||||
5. Build: `pnpm build`
|
||||
6. Commit with conventional format: `feat(#issue): Description`
|
||||
7. Push and create a pull request to `develop`
|
||||
|
||||
### Commit Format
|
||||
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
**Types:** `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- **Minimum 85% coverage** for new code
|
||||
- **TDD approach** — Write tests before implementation
|
||||
- **All tests pass** before PR merge
|
||||
- Use Vitest for unit/integration tests
|
||||
- Use Playwright for E2E tests
|
||||
|
||||
## Documentation
|
||||
|
||||
Complete documentation is organized in a Bookstack-compatible structure in the `docs/` directory.
|
||||
|
||||
### 📚 Getting Started
|
||||
|
||||
- **[Quick Start](docs/1-getting-started/1-quick-start/1-overview.md)** — Get running in 5 minutes
|
||||
- **[Installation](docs/1-getting-started/2-installation/)** — Prerequisites, local setup, Docker deployment
|
||||
- **[Configuration](docs/1-getting-started/3-configuration/)** — Environment variables and Authentik OIDC
|
||||
|
||||
### 💻 Development
|
||||
|
||||
- **[Workflow](docs/2-development/1-workflow/)** — Branching strategy, testing requirements, commit guidelines
|
||||
- **[Database](docs/2-development/2-database/)** — Schema design, migrations, Prisma usage
|
||||
- **[Type Sharing](docs/2-development/3-type-sharing/1-strategy.md)** — Shared types across monorepo
|
||||
|
||||
### 🏗️ Architecture
|
||||
|
||||
- **[Overview](docs/3-architecture/1-overview/)** — System design and components
|
||||
- **[Authentication](docs/3-architecture/2-authentication/)** — BetterAuth and OIDC integration
|
||||
- **[Design Principles](docs/3-architecture/3-design-principles/1-pda-friendly.md)** — PDA-friendly patterns (non-negotiable)
|
||||
|
||||
### 🔌 API Reference
|
||||
|
||||
- **[Conventions](docs/4-api/1-conventions/1-endpoints.md)** — REST patterns, pagination, filtering
|
||||
- **[Authentication](docs/4-api/2-authentication/1-endpoints.md)** — Auth endpoints and flows
|
||||
|
||||
**Browse all documentation:** [docs/](docs/)
|
||||
|
||||
## Related Projects
|
||||
|
||||
- **jarvis-brain** — Original JSON-based personal assistant (migration source)
|
||||
- **MoltBot** — Stock messaging gateway for multi-platform integration
|
||||
|
||||
## Security
|
||||
|
||||
- **Session-based authentication** with secure JWT tokens
|
||||
- **Row-level security** ready for multi-tenant isolation
|
||||
- **OIDC integration** with Authentik for enterprise SSO
|
||||
- **Secure error handling** — No sensitive data in logs or responses
|
||||
- **Type-safe validation** — TypeScript catches issues at compile time
|
||||
|
||||
## License
|
||||
|
||||
[Add license information]
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues:** https://git.mosaicstack.dev/mosaic/stack/issues
|
||||
- **Documentation:** https://git.mosaicstack.dev/mosaic/stack/wiki
|
||||
|
||||
---
|
||||
|
||||
**Mosaic Stack v0.0.1** — Building the future of personal assistants.
|
||||
Reference in New Issue
Block a user