# 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.