refactoring Single Source of Truth
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
# Meldestelle Project Guidelines
|
||||
|
||||
**Version:** 2.0.0
|
||||
**Last Updated:** 2025-09-13
|
||||
**Status:** Reorganized & AI-Optimized
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This directory contains the comprehensive development guidelines for the Meldestelle project. The guidelines have been restructured into a hierarchical, AI-assistant-optimized format for better navigation, maintainability, and usability.
|
||||
|
||||
> **🤖 AI-Assistant Note:**
|
||||
> All guidelines now include structured metadata headers and AI-specific hints for optimal assistant interaction:
|
||||
> - **Metadata:** Each file has guideline_type, scope, audience, and dependencies
|
||||
> - **AI Context:** Specific context information for better AI understanding
|
||||
> - **Cross-References:** Consistent navigation links between related guidelines
|
||||
> - **Quick Reference:** AI-optimized tables and checklists
|
||||
|
||||
## 🗂️ Guidelines Structure
|
||||
|
||||
### 📊 Master Guideline
|
||||
- **[Master-Guideline](./master-guideline.md)** - Central project guidelines and architectural foundations
|
||||
|
||||
### 🏗️ Project Standards
|
||||
Core development standards and quality requirements:
|
||||
|
||||
| Guideline | Scope | AI Context |
|
||||
|-----------|-------|------------|
|
||||
| [Coding Standards](./project-standards/coding-standards.md) | Code quality, naming conventions, patterns | Kotlin standards, Result pattern, value classes |
|
||||
| [Testing Standards](./project-standards/testing-standards.md) | Test strategies, tools, coverage | Test pyramid, Testcontainers, debugging |
|
||||
| [Documentation Standards](./project-standards/documentation-standards.md) | Documentation language, structure, API docs | German language rules, README templates |
|
||||
| [Architecture Principles](./project-standards/architecture-principles.md) | Microservices, DDD, EDA, KMP | Clean Architecture, bounded contexts, MVVM |
|
||||
|
||||
### 🔧 Technology Guides
|
||||
Technology-specific implementation guidelines:
|
||||
|
||||
#### Web Applications
|
||||
- **[Web App Guideline](./technology-guides/web-app-guideline.md)** - Compose Multiplatform development for desktop and web clients
|
||||
|
||||
#### Docker & Infrastructure
|
||||
| Docker Module | Focus Area | AI Context |
|
||||
|---------------|------------|------------|
|
||||
| [Docker Overview](./technology-guides/docker/docker-overview.md) | Philosophy and principles | Container strategy, security-first approach |
|
||||
| [Docker Architecture](./technology-guides/docker/docker-architecture.md) | Services and version management | Service categories, centralized versions |
|
||||
| [Docker Development](./technology-guides/docker/docker-development.md) | Development workflow | Makefile commands, debugging, hot-reload |
|
||||
| [Docker Production](./technology-guides/docker/docker-production.md) | Production deployment | Security hardening, SSL/TLS, monitoring |
|
||||
| [Docker Monitoring](./technology-guides/docker/docker-monitoring.md) | Observability setup | Prometheus, Grafana, health checks |
|
||||
| [Docker Troubleshooting](./technology-guides/docker/docker-troubleshooting.md) | Problem resolution | Common issues, best practices, workflows |
|
||||
|
||||
### 🔄 Process Guides
|
||||
Development process and workflow guidelines:
|
||||
|
||||
- **[Trace Bullet Guideline](./process-guides/trace-bullet-guideline.md)** - End-to-end architecture validation cycle
|
||||
|
||||
## 🎯 Quick Navigation for AI Assistants
|
||||
|
||||
### Common Development Tasks
|
||||
|
||||
| Task | Primary Guidelines | Supporting Guidelines |
|
||||
|------|-------------------|----------------------|
|
||||
| **New Feature Development** | Architecture Principles, Coding Standards | Testing Standards, Docker Development |
|
||||
| **Frontend Development** | Web App Guideline | Architecture Principles, Coding Standards |
|
||||
| **Backend Service Creation** | Architecture Principles, Coding Standards | Docker Development, Testing Standards |
|
||||
| **Infrastructure Setup** | Docker Architecture, Docker Development | Docker Overview, Docker Monitoring |
|
||||
| **Production Deployment** | Docker Production | Docker Architecture, Docker Monitoring |
|
||||
| **Testing Implementation** | Testing Standards | Coding Standards, Docker Development |
|
||||
| **Documentation Writing** | Documentation Standards | All related technical guidelines |
|
||||
| **Troubleshooting Issues** | Docker Troubleshooting | Docker Development, Docker Monitoring |
|
||||
|
||||
### Key Architectural Decisions
|
||||
|
||||
1. **Microservices Architecture** - See [Architecture Principles](./project-standards/architecture-principles.md)
|
||||
2. **Domain-Driven Design** - See [Architecture Principles](./project-standards/architecture-principles.md)
|
||||
3. **Event-Driven Architecture** - See [Architecture Principles](./project-standards/architecture-principles.md)
|
||||
4. **Kotlin Multiplatform** - See [Web App Guideline](./technology-guides/web-app-guideline.md)
|
||||
5. **Docker-First Infrastructure** - See [Docker Overview](./technology-guides/docker/docker-overview.md)
|
||||
|
||||
### Technology Stack Quick Reference
|
||||
|
||||
| Layer | Technologies | Guidelines |
|
||||
|-------|-------------|------------|
|
||||
| **Frontend** | Kotlin Multiplatform, Compose Multiplatform | Web App Guideline |
|
||||
| **Backend** | Spring Boot, Kotlin, Clean Architecture | Architecture Principles, Coding Standards |
|
||||
| **Infrastructure** | Docker, PostgreSQL, Redis, Kafka, Consul | Docker Guides |
|
||||
| **Monitoring** | Prometheus, Grafana, Zipkin | Docker Monitoring |
|
||||
| **Testing** | JUnit 5, MockK, Testcontainers | Testing Standards |
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### For Developers
|
||||
1. Start with [Master-Guideline](./master-guideline.md) for project overview
|
||||
2. Review [Architecture Principles](./project-standards/architecture-principles.md) for architectural foundations
|
||||
3. Follow [Coding Standards](./project-standards/coding-standards.md) for development practices
|
||||
4. Use [Docker Development](./technology-guides/docker/docker-development.md) for local setup
|
||||
|
||||
### For AI Assistants
|
||||
1. Each guideline includes structured metadata and AI context
|
||||
2. Use the `ai_context` field for understanding guideline scope
|
||||
3. Cross-reference related guidelines through navigation sections
|
||||
4. Leverage quick reference tables for rapid information access
|
||||
|
||||
### For Project Managers
|
||||
1. [Trace Bullet Guideline](./process-guides/trace-bullet-guideline.md) for current development cycle
|
||||
2. [Master-Guideline](./master-guideline.md) for project standards overview
|
||||
3. Individual guidelines for specific team coordination
|
||||
|
||||
## 📝 Guideline Metadata Format
|
||||
|
||||
All guidelines follow this metadata structure for AI optimization:
|
||||
|
||||
```yaml
|
||||
---
|
||||
guideline_type: "project-standards" | "technology" | "process-guide"
|
||||
scope: "specific-area-identifier"
|
||||
audience: ["developers", "ai-assistants", "architects", "devops", "project-managers"]
|
||||
last_updated: "YYYY-MM-DD"
|
||||
dependencies: ["list-of-related-guidelines"]
|
||||
related_files: ["relevant-project-files"]
|
||||
ai_context: "Brief description for AI understanding"
|
||||
---
|
||||
```
|
||||
|
||||
## 🔍 Guidelines Maintenance
|
||||
|
||||
### Update Process
|
||||
1. **Content Changes** → Update specific guideline file
|
||||
2. **Structural Changes** → Update README.md navigation
|
||||
3. **New Guidelines** → Add to appropriate category and update index
|
||||
4. **Deprecated Guidelines** → Archive and update references
|
||||
|
||||
### Quality Assurance
|
||||
- All guidelines include AI-optimized metadata
|
||||
- Cross-references are maintained and validated
|
||||
- Navigation links are consistent across guidelines
|
||||
- Content follows documentation standards
|
||||
|
||||
---
|
||||
|
||||
**Last Restructuring:** 2025-09-13 - Complete hierarchical reorganization with AI optimization
|
||||
**Next Review:** As needed based on project evolution
|
||||
|
||||
**Questions or suggestions?** Update this README.md or reach out to the development team.
|
||||
Reference in New Issue
Block a user