161 lines
8.1 KiB
Markdown
161 lines
8.1 KiB
Markdown
# Meldestelle Project Guidelines
|
|
|
|
**Version:** 2.1.0
|
|
**Last Updated:** 2025-09-15
|
|
**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
|
|
|
|
## 🤖 Automatisierung und Validierung
|
|
|
|
Das Guidelines-System verfügt über umfassende Automatisierungsfeatures:
|
|
|
|
### 🔗 Automatische Validierung
|
|
- **Link-Validierung:** `.junie/scripts/validate-links.sh` - Cross-Referenzen und YAML-Konsistenz
|
|
- **Template-System:** `.junie/scripts/create-guideline.sh` - Automatische Guideline-Erstellung
|
|
- **Pre-commit Hook:** `.junie/scripts/pre-commit-guidelines.sh` - Lokale Validierung vor Commits
|
|
- **CI/CD-Integration:** `.github/workflows/guidelines-validation.yml` - Automatische Pipeline-Validierung
|
|
|
|
### 📋 Verfügbare Templates
|
|
- **Project-Standards:** `project-standard-template.md`
|
|
- **Technology-Guides:** `technology-guideline-template.md`
|
|
- **Process-Guides:** `process-guide-template.md`
|
|
|
|
**Detaillierte Dokumentation:** [AUTOMATION-FEATURES.md](../AUTOMATION-FEATURES.md)
|
|
|
|
## 📝 Guideline Metadata Format
|
|
|
|
All guidelines follow this metadata structure for AI optimization:
|
|
|
|
```yaml
|
|
---
|
|
guideline_type: "project-standards" # oder "technology" oder "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.
|