mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 23:01:09 +02:00
ad495b2044
Optimize CLAUDE.md based on industry best practices from HN and HumanLayer:
Changes:
- Trim CLAUDE.md from 678 to 176 lines (74% reduction, 5.7KB)
- Add "Critical Gotchas" section for common AI mistakes
- Add verification signature (🏗️ ManaCore Monorepo)
- Create docs/README.md navigation hub with "I want to..." index
- Delete 5 outdated audit files (ENV_AUDIT_*, DEPENDENCY_ALIGNMENT)
- Archive 7 analysis/historical docs to docs/archive/
- Keep authentication docs separate per request (.claude/guidelines/)
Benefits:
- Better AI instruction adherence (within ~150-200 line budget)
- Progressive disclosure via signposting to detailed docs
- Cleaner navigation with topic-based organization
- Reduced maintenance burden (stale docs archived)
Backup: CLAUDE.md.backup preserves original 678-line version
Change log: docs/archive/RESTRUCTURE_2025-12-16.md
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 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](getting-started/local-development.md) |
|
|
| **Set up environment variables** | [Environment Setup](../CLAUDE.md#environment-variables) |
|
|
| **Understand the architecture** | [Deployment Architecture](DEPLOYMENT_ARCHITECTURE.md) |
|
|
| **Work with databases** | [Database Migrations](DATABASE_MIGRATIONS.md) |
|
|
| **Deploy to staging** | [Staging Setup](STAGING_SETUP.md) |
|
|
| **Deploy to production** | [Deployment Runbooks](DEPLOYMENT_RUNBOOKS.md) |
|
|
| **Use Docker locally** | [Docker Guide](DOCKER_GUIDE.md) |
|
|
| **Debug an issue** | [Staging Issues](STAGING_DEPLOYMENT_ISSUES.md) |
|
|
| **Learn code patterns** | [Guidelines](../.claude/GUIDELINES.md) |
|
|
| **Configure CI/CD** | [CI/CD Setup](CI_CD_SETUP.md) |
|
|
| **Work with runtime config** | [Runtime Config](RUNTIME_CONFIG.md) |
|
|
| **Self-host the platform** | [Self-Hosting Guide](SELF-HOSTING-GUIDE.md) |
|
|
|
|
## 📁 Documentation Structure
|
|
|
|
### Getting Started
|
|
First-time setup, environment configuration, and basic workflows.
|
|
- [Local Development](LOCAL_DEVELOPMENT.md) - Complete local development setup
|
|
- [Setup Templates](SETUP_TEMPLATES.md) - Templates for new projects
|
|
|
|
### Architecture & Design
|
|
System design, technology choices, and architectural patterns.
|
|
- [Deployment Architecture](DEPLOYMENT_ARCHITECTURE.md) - Complete infrastructure overview
|
|
- [Deployment Diagrams](DEPLOYMENT_DIAGRAMS.md) - Visual architecture diagrams
|
|
|
|
### Development Workflows
|
|
Day-to-day development, migrations, and Docker.
|
|
- [Database Migrations](DATABASE_MIGRATIONS.md) - Migration best practices
|
|
- [Docker Guide](DOCKER_GUIDE.md) - Local Docker setup
|
|
- [Git Workflow](GIT_WORKFLOW.md) - Git branching and commit conventions
|
|
- [Development Scripts](DEVELOPMENT_SCRIPTS.md) - Helper scripts
|
|
|
|
### Deployment & Operations
|
|
CI/CD, staging, production deployment, and operational procedures.
|
|
- [Deployment Overview](DEPLOYMENT.md) - Deployment strategy overview
|
|
- [Deployment Runbooks](DEPLOYMENT_RUNBOOKS.md) - Step-by-step deployment procedures
|
|
- [Staging Setup](STAGING_SETUP.md) - Hetzner staging environment
|
|
- [Staging Issues](STAGING_DEPLOYMENT_ISSUES.md) - Known issues and solutions
|
|
- [Hetzner Production Guide](HETZNER_PRODUCTION_GUIDE.md) - Production deployment
|
|
- [CI/CD Setup](CI_CD_SETUP.md) - GitHub Actions configuration
|
|
- [Runtime Config](RUNTIME_CONFIG.md) - Dynamic configuration injection
|
|
|
|
### Specialized Topics
|
|
- [PWA Guide](PWA_GUIDE.md) - Progressive Web App setup
|
|
- [I18N](I18N.md) - Internationalization
|
|
- [User Settings](USER_SETTINGS.md) - User settings architecture
|
|
- [Self-Hosting Guide](SELF-HOSTING-GUIDE.md) - Self-hosting instructions
|
|
- [Testing Guide](TESTING.md) - Testing strategies
|
|
|
|
### Project-Specific
|
|
- [ManaDeck Postgres Migration](MANADECK_POSTGRES_MIGRATION.md) - ManaDeck database migration
|
|
- [Uload Deployment](ULOAD-DEPLOYMENT.md) - Uload-specific deployment
|
|
|
|
### Archived Documentation
|
|
Historical documentation and analysis reports moved to [archive/](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](../CLAUDE.md) for essential patterns
|
|
- Reference [Guidelines](../.claude/GUIDELINES.md) 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
|