mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
95fe3e0573e700f223dbe404eb832f78e40f869f
meldestelle/.junie/guidelines
T
History
StefanMo 95fe3e0573 chore(ci): Align GH Workflows with Docker SSoT, new paths; minimal SSoT guard; staticAnalysis (#23) 
* chore(MP-21): snapshot pre-refactor state (Epic 1)

* chore(MP-22): scaffold new repo structure, relocate Docker Compose, move frontend/backend modules, update Makefile; add docs mapping and env template

* MP-22 Epic 2: Erfolgreich umgesetzt und verifiziert

* MP-23 Epic 3: Gradle/Build Governance zentralisieren

* MP-23 Epic 3: Gradle/Build Governance zentralisieren

* chore(devops)!: Docker-SSoT (.env) konsolidiert, Compose-Mounts ergänzt, Makefile entfernt

- ENV Single Source of Truth
  - docker/.env.example neu (inkl. REDIS_PASSWORD, Ports, Build-Overrides)
  - config/.env(.example) als DEPRECATED markiert (Verweis auf docker/.env[.example])

- Docker Compose vereinheitlicht (docker/docker-compose.yaml)
  - Postgres: zentralen postgresql.conf mounten (../config/postgres/postgresql.conf)
    und Start mit -c config_file=/etc/postgresql/postgresql.conf
  - Redis: zentralen redis.conf mounten (../config/redis/redis.conf)
    und Start via "redis-server … ${REDIS_PASSWORD:+--requirepass $REDIS_PASSWORD}"
  - Web-Nginx: ../config/nginx/nginx.prod.conf → /etc/nginx/nginx.conf (ro)
  - Monitoring: Prometheus/Grafana nutzen ../config/monitoring/* als SSoT

- Frontend/DI/Network (MP-23 Grundlage)
  - :frontend:core:network Modul mit Koin `apiClient` (Ktor + JSON/Retry/Timeout/Logging)
  - Plattform-Basis-URL-Auflösung (JVM: ENV API_BASE_URL; JS: globalThis.API_BASE_URL / Same-Origin)
  - Web index.html setzt API_BASE_URL (Query `?apiBaseUrl=…` > Same-Origin > Fallback)

- Build/Gradle & Module-Refs
  - settings.gradle.kts: neue Frontend-/Backend-Pfade bereits inkludiert
  - Features/Shell: Abhängigkeiten auf :frontend:shared / :frontend:core:* angepasst
  - Ping-API-Refs auf :backend:services:ping:ping-api vereinheitlicht

- Dockerfiles angepasst
  - backend/infrastructure/gateway/Dockerfile → Tasks/Pfade auf :backend:gateway
  - backend/services/ping/Dockerfile → Tasks/Pfade auf :backend:services:ping:ping-service

- Static Analysis / Guards
  - config/detekt/detekt.yml hinzugefügt
  - Leichter Arch-Guard (Frontend) gegen manuelle Authorization-Header vorbereitet

- Doku
  - docs/ARCHITECTURE.md (Struktur, Mapping, Next Steps) ergänzt
  - docs/adr/README.md angelegt

BREAKING CHANGES:
- Makefile komplett entfernt (bitte direkt `docker compose` verwenden)
- ENV-Quelle ist jetzt docker/.env (statt config/.env oder Root)
- Compose-Datei unter docker/docker-compose.yaml (nicht mehr compose.yaml im Repo-Root)

Verifikation (lokal):
- ENV anlegen: `cp docker/.env.example docker/.env` (Werte anpassen)
- Compose prüfen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml config`
- Infrastruktur: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle up -d postgres redis keycloak web-app`
- Services bauen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle build api-gateway ping-service --no-cache --progress=plain`

Refs: MP-22 (Epic 2), MP-23 (Epic 3)

* chore(devops)!: Docker-SSoT (.env) konsolidiert, Compose-Mounts ergänzt, Makefile entfernt

- ENV Single Source of Truth
  - docker/.env.example neu (inkl. REDIS_PASSWORD, Ports, Build-Overrides)
  - config/.env(.example) als DEPRECATED markiert (Verweis auf docker/.env[.example])

- Docker Compose vereinheitlicht (docker/docker-compose.yaml)
  - Postgres: zentralen postgresql.conf mounten (../config/postgres/postgresql.conf)
    und Start mit -c config_file=/etc/postgresql/postgresql.conf
  - Redis: zentralen redis.conf mounten (../config/redis/redis.conf)
    und Start via "redis-server … ${REDIS_PASSWORD:+--requirepass $REDIS_PASSWORD}"
  - Web-Nginx: ../config/nginx/nginx.prod.conf → /etc/nginx/nginx.conf (ro)
  - Monitoring: Prometheus/Grafana nutzen ../config/monitoring/* als SSoT

- Frontend/DI/Network (MP-23 Grundlage)
  - :frontend:core:network Modul mit Koin `apiClient` (Ktor + JSON/Retry/Timeout/Logging)
  - Plattform-Basis-URL-Auflösung (JVM: ENV API_BASE_URL; JS: globalThis.API_BASE_URL / Same-Origin)
  - Web index.html setzt API_BASE_URL (Query `?apiBaseUrl=…` > Same-Origin > Fallback)

- Build/Gradle & Module-Refs
  - settings.gradle.kts: neue Frontend-/Backend-Pfade bereits inkludiert
  - Features/Shell: Abhängigkeiten auf :frontend:shared / :frontend:core:* angepasst
  - Ping-API-Refs auf :backend:services:ping:ping-api vereinheitlicht

- Dockerfiles angepasst
  - backend/infrastructure/gateway/Dockerfile → Tasks/Pfade auf :backend:gateway
  - backend/services/ping/Dockerfile → Tasks/Pfade auf :backend:services:ping:ping-service

- Static Analysis / Guards
  - config/detekt/detekt.yml hinzugefügt
  - Leichter Arch-Guard (Frontend) gegen manuelle Authorization-Header vorbereitet

- Doku
  - docs/ARCHITECTURE.md (Struktur, Mapping, Next Steps) ergänzt
  - docs/adr/README.md angelegt

BREAKING CHANGES:
- Makefile komplett entfernt (bitte direkt `docker compose` verwenden)
- ENV-Quelle ist jetzt docker/.env (statt config/.env oder Root)
- Compose-Datei unter docker/docker-compose.yaml (nicht mehr compose.yaml im Repo-Root)

Verifikation (lokal):
- ENV anlegen: `cp docker/.env.example docker/.env` (Werte anpassen)
- Compose prüfen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml config`
- Infrastruktur: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle up -d postgres redis keycloak web-app`
- Services bauen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle build api-gateway ping-service --no-cache --progress=plain`

Refs: MP-22 (Epic 2), MP-23 (Epic 3)

* chore(devops)!: Docker-SSoT (.env) konsolidiert, Compose-Mounts ergänzt, Makefile entfernt

- ENV Single Source of Truth
  - docker/.env.example neu (inkl. REDIS_PASSWORD, Ports, Build-Overrides)
  - config/.env(.example) als DEPRECATED markiert (Verweis auf docker/.env[.example])

- Docker Compose vereinheitlicht (docker/docker-compose.yaml)
  - Postgres: zentralen postgresql.conf mounten (../config/postgres/postgresql.conf)
    und Start mit -c config_file=/etc/postgresql/postgresql.conf
  - Redis: zentralen redis.conf mounten (../config/redis/redis.conf)
    und Start via "redis-server … ${REDIS_PASSWORD:+--requirepass $REDIS_PASSWORD}"
  - Web-Nginx: ../config/nginx/nginx.prod.conf → /etc/nginx/nginx.conf (ro)
  - Monitoring: Prometheus/Grafana nutzen ../config/monitoring/* als SSoT

- Frontend/DI/Network (MP-23 Grundlage)
  - :frontend:core:network Modul mit Koin `apiClient` (Ktor + JSON/Retry/Timeout/Logging)
  - Plattform-Basis-URL-Auflösung (JVM: ENV API_BASE_URL; JS: globalThis.API_BASE_URL / Same-Origin)
  - Web index.html setzt API_BASE_URL (Query `?apiBaseUrl=…` > Same-Origin > Fallback)

- Build/Gradle & Module-Refs
  - settings.gradle.kts: neue Frontend-/Backend-Pfade bereits inkludiert
  - Features/Shell: Abhängigkeiten auf :frontend:shared / :frontend:core:* angepasst
  - Ping-API-Refs auf :backend:services:ping:ping-api vereinheitlicht

- Dockerfiles angepasst
  - backend/infrastructure/gateway/Dockerfile → Tasks/Pfade auf :backend:gateway
  - backend/services/ping/Dockerfile → Tasks/Pfade auf :backend:services:ping:ping-service

- Static Analysis / Guards
  - config/detekt/detekt.yml hinzugefügt
  - Leichter Arch-Guard (Frontend) gegen manuelle Authorization-Header vorbereitet

- Doku
  - docs/ARCHITECTURE.md (Struktur, Mapping, Next Steps) ergänzt
  - docs/adr/README.md angelegt

BREAKING CHANGES:
- Makefile komplett entfernt (bitte direkt `docker compose` verwenden)
- ENV-Quelle ist jetzt docker/.env (statt config/.env oder Root)
- Compose-Datei unter docker/docker-compose.yaml (nicht mehr compose.yaml im Repo-Root)

Verifikation (lokal):
- ENV anlegen: `cp docker/.env.example docker/.env` (Werte anpassen)
- Compose prüfen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml config`
- Infrastruktur: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle up -d postgres redis keycloak web-app`
- Services bauen: `docker compose --env-file docker/.env -f docker/docker-compose.yaml -p meldestelle build api-gateway ping-service --no-cache --progress=plain`

Refs: MP-22 (Epic 2), MP-23 (Epic 3)

* chore(ci): Workflows an Docker-SSoT & neue Struktur angepasst, minimaler SSoT-Guard

- ssot-guard.yml: Option B (minimal) → `docker compose -f docker/docker-compose.yaml config` als Lint
- integration-tests.yml: `./gradlew staticAnalysis` vor Integrationstests
- docs-kdoc-sync.yml: Dokka-Task Fallback (dokkaGfmAll || dokkaGfm), YouTrack-Sync nur wenn Script vorhanden
- deploy-proxmox.yml: Compose-Pfade auf docker/docker-compose.yaml + `--env-file docker/.env`; Build/Test Schritte vereinheitlicht
- ci-main.yml: SSoT-Skripte per `if: hashFiles(...)` guarded, Compose-Lint Fallback; OpenAPI‑Pfad → backend/gateway; ADR‑Pfade → docs/adr/**; `staticAnalysis` in Build integriert
- youtrack-sync.yml: unverändert (funktional)

Refs: MP-22, MP-23

* chore(ci): Workflows an Docker-SSoT & neue Struktur angepasst, minimaler SSoT-Guard

- ssot-guard.yml: Option B (minimal) → `docker compose -f docker/docker-compose.yaml config` als Lint
- integration-tests.yml: `./gradlew staticAnalysis` vor Integrationstests
- docs-kdoc-sync.yml: Dokka-Task Fallback (dokkaGfmAll || dokkaGfm), YouTrack-Sync nur wenn Script vorhanden
- deploy-proxmox.yml: Compose-Pfade auf docker/docker-compose.yaml + `--env-file docker/.env`; Build/Test Schritte vereinheitlicht
- ci-main.yml: SSoT-Skripte per `if: hashFiles(...)` guarded, Compose-Lint Fallback; OpenAPI‑Pfad → backend/gateway; ADR‑Pfade → docs/adr/**; `staticAnalysis` in Build integriert
- youtrack-sync.yml: unverändert (funktional)

Refs: MP-22, MP-23

* fix(ci): create .env from example before validating compose config

* fix(ci): update ssot-guard filename (.yaml) and sync workflow state

* fixing

* fix(webpack): correct sql.js fallback configuration for webpack 5
2025-12-03 12:03:40 +01:00
..
_archived
chore(ci): Align GH Workflows with Docker SSoT, new paths; minimal SSoT guard; staticAnalysis (#23)
2025-12-03 12:03:40 +01:00
_meta
fixing .junie
2025-09-15 12:49:55 +02:00
_templates
Fix: Test-Commit für VCS-Integration (MP-8) (#15)
2025-11-07 12:26:33 +01:00
process-guides
Fix: Test-Commit für VCS-Integration (MP-8) (#15)
2025-11-07 12:26:33 +01:00
project-standards
Fix: Test-Commit für VCS-Integration (MP-8) (#15)
2025-11-07 12:26:33 +01:00
technology-guides
chore(ci): Align GH Workflows with Docker SSoT, new paths; minimal SSoT guard; staticAnalysis (#23)
2025-12-03 12:03:40 +01:00
master-guideline.md
Fix: Test-Commit für VCS-Integration (MP-8) (#15)
2025-11-07 12:26:33 +01:00
README.md
Fix: Test-Commit für VCS-Integration (MP-8) (#15)
2025-11-07 12:26:33 +01:00

README.md

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

🏗️ 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

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:

🎯 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

🤖 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 (optional): .github/workflows/ci-main.yml (Job: validate-docs) - Markdown-Lint und Link-Check für kritische Docs

📋 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

📝 Guideline Metadata Format

All guidelines follow this metadata structure for AI optimization:

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

Reference in New Issue View Git Blame Copy Permalink