managarten/docs/README.md

Manacore Monorepo Documentation

Welcome to the Manacore monorepo documentation. This guide helps you find exactly what you need.

🚀 Quick Navigation

I want to...	Go here
Start developing locally	Local Development
Set up environment variables	Environment Setup
Understand the architecture	Deployment Architecture
Work with databases	Database Migrations
Deploy to staging	Staging Setup
Deploy to production	Deployment Runbooks
Use Docker locally	Docker Guide
Debug an issue	Staging Issues
Learn code patterns	Guidelines
Configure CI/CD	CI/CD Setup
Work with runtime config	Runtime Config
Self-host the platform	Self-Hosting Guide

📁 Documentation Structure

Getting Started

First-time setup, environment configuration, and basic workflows.

• Local Development - Complete local development setup
• Setup Templates - Templates for new projects

Architecture & Design

System design, technology choices, and architectural patterns.

• Deployment Architecture - Complete infrastructure overview
• Deployment Diagrams - Visual architecture diagrams

Development Workflows

Day-to-day development, migrations, and Docker.

• Database Migrations - Migration best practices
• Docker Guide - Local Docker setup
• Git Workflow - Git branching and commit conventions
• Development Scripts - Helper scripts

Deployment & Operations

CI/CD, staging, production deployment, and operational procedures.

• Deployment Overview - Deployment strategy overview
• Deployment Runbooks - Step-by-step deployment procedures
• Staging Setup - Hetzner staging environment
• Staging Issues - Known issues and solutions
• Hetzner Production Guide - Production deployment
• CI/CD Setup - GitHub Actions configuration
• Runtime Config - Dynamic configuration injection

Specialized Topics

• PWA Guide - Progressive Web App setup
• I18N - Internationalization
• User Settings - User settings architecture
• Self-Hosting Guide - Self-hosting instructions
• Testing Guide - Testing strategies

Project-Specific

• ManaDeck Postgres Migration - ManaDeck database migration
• Uload Deployment - Uload-specific deployment

Archived Documentation

Historical documentation and analysis reports moved to archive/.

🎯 Documentation Philosophy

This documentation follows these principles:

1. Progressive Disclosure - Start with essentials, link to deep dives
2. Single Source of Truth - Each topic has one authoritative document
3. Task-Oriented - Organized by what you're trying to accomplish
4. Keep Current - Archive or delete outdated docs instead of letting them linger

📝 For AI Assistants

If you're Claude or another AI assistant:

• Start with CLAUDE.md for essential patterns
• Reference Guidelines for detailed coding patterns
• Use this README to find specific documentation topics
• Always check file modification dates to ensure information is current

🔄 Maintenance

When updating documentation:

• Update this README if you add/move/remove major docs
• Archive outdated docs to archive/ rather than deleting
• Keep cross-references up to date
• Update the modification date in this file

---

Last Updated: 2025-12-16