meldestelle/.junie/guidelines/README.md

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 - Central project guidelines and architectural foundations

🏗️ Project Standards

Core development standards and quality requirements:

Guideline	Scope	AI Context
Coding Standards	Code quality, naming conventions, patterns	Kotlin standards, Result pattern, value classes
Testing Standards	Test strategies, tools, coverage	Test pyramid, Testcontainers, debugging
Documentation Standards	Documentation language, structure, API docs	German language rules, README templates
Architecture Principles	Microservices, DDD, EDA, KMP	Clean Architecture, bounded contexts, MVVM

🔧 Technology Guides

Technology-specific implementation guidelines:

Web Applications

• Web App Guideline - Compose Multiplatform development for desktop and web clients

Docker & Infrastructure

Docker Module	Focus Area	AI Context
Docker Overview	Philosophy and principles	Container strategy, security-first approach
Docker Architecture	Services and version management	Service categories, centralized versions
Docker Development	Development workflow	Makefile commands, debugging, hot-reload
Docker Production	Production deployment	Security hardening, SSL/TLS, monitoring
Docker Monitoring	Observability setup	Prometheus, Grafana, health checks
Docker Troubleshooting	Problem resolution	Common issues, best practices, workflows

🔄 Process Guides

Development process and workflow guidelines:

• Trace Bullet Guideline - 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
2. Domain-Driven Design - See Architecture Principles
3. Event-Driven Architecture - See Architecture Principles
4. Kotlin Multiplatform - See Web App Guideline
5. Docker-First Infrastructure - See Docker Overview

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 for project overview
2. Review Architecture Principles for architectural foundations
3. Follow Coding Standards for development practices
4. Use Docker Development 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 for current development cycle
2. Master-Guideline for project standards overview
3. Individual guidelines for specific team coordination

📝 Guideline Metadata Format

All guidelines follow this metadata structure for AI optimization:

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