Guidelines Overview

Knowledge Base – Table of Contents

MANDATORY FOR ALL AI AGENTS: You MUST read and follow every guide listed below IN ORDER before generating any code. Each guide contains binding architectural rules. Violations of hexagonal architecture boundaries are NOT acceptable. When creating new project resources (README, LICENSE, etc.), you MUST follow resources.md exactly. Failure to comply will produce code that is architecturally invalid.

Project-agnostic: these guidelines describe patterns, not a specific project. Code samples use placeholder package com.example.platform and service name platform-service. Replace with your project’s actual values when applying patterns.

Below is the table of contents for this knowledge base. Follow the sections in order.

Important: Do not move these guidelines to the project root folder.

For Developers

1. Resources (MANDATORY FIRST STEP)

   • YOU MUST generate all project resource files listed in this guide before writing any code.
   • Overview of helpful links, tools, and reference materials.
   • Open: Resources

2. Domain-Driven Design (DDD)

   • Building blocks: entities, value objects, aggregates, domain services, domain events.
   • Bounded contexts and ubiquitous language.
   • Open: DDD

3. Hexagonal Architecture

   • Ports and adapters, layer placement rules, dependency direction.
   • Transactional Outbox Pattern.
   • Chain of Responsibility Pattern.
   • Architecture testing with ArchUnit.
   • Cross-cutting concerns.
   • Open: Hexagonal Architecture

4. Architectural Decision Records (ADR)

   • When to write ADRs and what counts as architecturally significant.
   • MADR (default), Nygard, Y-Statement, ISO 42010 templates.
   • Status lifecycle (proposed → accepted → deprecated → superseded).
   • Naming, repo layout (docs/adr/), review checklist.
   • Hexagonal tie-ins (ports, adapters, transactions, outbox).
   • Open: ADR

5. Clean Code Principles

   • Clean code practices for hexagonal Kotlin/Java services.
   • Transaction abstraction patterns (Transaction port over @Transactional).
   • Open: Clean Code

6. Kotlin Code Style

   • Conventions, formatting rules, best practices.
   • data class vs class, lateinit vs nullable, fun interface, extension functions for mappers.
   • Kotlin-specific anti-patterns.
   • Open: Kotlin Code Style

7. Java Code Style

   • Conventions, formatting rules, best practices.
   • record vs class, @FunctionalInterface, null safety (@Nullable/@NonNull), mapper patterns.
   • Java-specific anti-patterns.
   • Open: Java Code Style

8. Spring Boot

   • Spring Boot patterns for hexagonal architecture.
   • Configuration strategies, transaction management, Spring Data JDBC, Kafka, Redis, Async, Scheduler.
   • Testing with Testcontainers and ArchUnit.
   • Open: Spring Boot

9. Eclipse Vert.x

   • Reactive layered N-tier + event-driven style (descriptive, not hexagonal).
   • Verticles + EventBus, Future API composition, worker offload, dual store (Pg/Mongo).
   • Testing with vertx-junit5 + Testcontainers; Shadow fat jar; Java 17 / Vert.x 4.x.
   • Open: Eclipse Vert.x

10. Testing Strategy

• Unit testing in Domain and Application layers.
• Integration testing with Karate DSL and Testcontainers.
• Architecture testing with ArchUnit (concrete examples).
• TDD workflow for hexagonal architecture.
• Open: Testing

11. Observability (OTEL / Micrometer)

    • Index + three-pillars overview.
    • Themed sub-files: obs-metrics.md, obs-tracing.md, obs-logging.md, obs-recipes.md (dashboards, alerting, step-by-step).
    • Custom metrics via decorator pattern, OTEL tracing automatic via Micrometer bridge, structured logs with trace correlation.
    • Open: Observability

12. Gradle Build System

    • Versions + bump policy (Java 21, Boot 4.0, Gradle 9.0, Kotlin optional 2.x).
    • Compiler config (Java + Kotlin), multi-module hexagonal layout, BootJar pattern.
    • Plugins: Spotless (Java + Kotlin), JaCoCo (per-module + aggregated + log table), SonarQube, Detekt (Kotlin), PlantUML, Structurizr C4.
    • Module naming: entry points, driven adapters, <provider>-adapter pattern (one per third-party).
    • SDK publishing: maven-publish + GitHub Packages + compileOnly Spring deps + Javadoc/Sources jars + SemVer.
    • BOM management (Spring Boot + Spring Cloud + AWS + Jackson + JUnit + Testcontainers).
    • Repository strategy, resolution strategy with because(), custom tasks, gradle.properties conventions.
    • Open: Gradle

13. Liquibase Migrations

    • Iron rule: never modify a committed changeset (checksum break = deploy abort).
    • Fix-forward with new changesets, not back-edits.
    • Environment-specific seeds via preconditions (single changelog, no test/prod fork).
    • Emergency escape hatches: clearCheckSums, validCheckSum ANY (rare).
    • Open: Liquibase

14. Security

    • STRIDE threat-model baseline, AuthN/AuthZ (OAuth2/OIDC/JWT/mTLS), Current User Port.
    • Secrets management, input validation, injection prevention, cryptography defaults.
    • Logging/PII rules, rate limiting/DoS, CORS/CSRF, audit trail via outbox.
    • Multi-tenant isolation (RLS + app filter), container hardening, compliance hooks.
    • Security testing matrix + pre-merge checklist.
    • Open: Security

15. Keycloak & Identity

    • Specializes Security for Keycloak: two topologies (gateway-first trusted-headers vs per-service resource server) — decision matrix + ADR trigger.
    • Realm/client/role setup as code, platform-{role} → ROLE_{ROLE} convention.
    • JwtAuthenticationConverter for realm_access + resource_access; trusted-header filter; Current User Port adapter per topology.
    • Dedicated auth microservice (KeycloakService port + Admin API adapter), grant-flow selection matrix, service-to-service tokens.
    • Multi-tenancy models, testcontainers-keycloak, anti-patterns + checklist.
    • Open: Keycloak

16. API Design

    • REST conventions: resource modeling, URL/method/status matrix, JSON shape.
    • Versioning (URL path default), error envelope (RFC 9457 Problem Details, obsoletes RFC 7807).
    • Pagination (cursor default), filtering/sorting/sparse fieldsets.
    • Idempotency-Key, caching/ETags/optimistic concurrency, rate-limit headers.
    • Async/long-running, bulk, file upload/download, webhooks, HATEOAS guidance.
    • OpenAPI contract-first, deprecation lifecycle, anti-patterns, pre-merge checklist.
    • Open: API Design

17. Messaging

    • Broker selection matrix (RabbitMQ / Kafka / SQS+SNS).
    • Canonical EventMessage<T> envelope (Header + Body) with auto-injected origin.
    • Transactional Outbox (write side reliability) + claim-based dispatch + ShedLock per-service.
    • Retry/backoff/DLT, idempotent consumers, schema evolution + coexistence.
    • Topology externalization (no @Bean Queue/Exchange/Binding/NewTopic).
    • RabbitMQ + Kafka specifics, tracing propagation, choreography vs orchestration.
    • Reference impl: codehuntersio-sdk-event-messaging.
    • Open: Messaging

18. API Gateway

    • Tier responsibilities (CDN/WAF → gateway → service mesh → service).
    • Gateway selection matrix (KrakenD / Kong / SCG / AWS APIGW / Apigee).
    • KrakenD canonical reference: Flexible Configuration template, per-concern settings split, env-override pattern, Go custom plugins (.so).
    • Edge AuthN (JWT via JWKS) + claims-to-headers forwarding + skip-paths.
    • Edge rate limiting, CORS, W3C Trace Context propagation (with legacy Trace-Id fallback).
    • mTLS to backends, aggregation patterns (thin client / thick gateway), edge caching, service discovery.
    • Observability (metrics, JSON logs, OTEL spans), deployment, 16 anti-patterns + checklist.
    • Open: API Gateway

19. GitOps + ArgoCD

    • OpenGitOps principles (declarative, versioned, pulled, continuously reconciled).
    • CI/CD boundary: CI builds + writes commit; ArgoCD applies. CI never holds cluster credentials.
    • Repo topology (split app + GitOps, env folders), bootstrap, App-of-Apps + ApplicationSet (matrix, PR-preview, cluster generators).
    • Sync policies (auto + prune + self-heal), sync waves, hooks (PreSync DB migration, PostSync smoke).
    • Multi-env with Kustomize, Helm only for third-party charts (pinned versions, OCI).
    • Promotion strategy (folder copy default, tag-based via Image Updater, Kargo/argo-promotion).
    • Secrets management (Sealed Secrets / External Secrets Operator / SOPS) — never plaintext in Git.
    • Progressive delivery (Argo Rollouts canary + AnalysisTemplate via Prometheus).
    • Drift detection, notifications, custom Lua health checks, multi-cluster hub-spoke, DR runbook.
    • 20 anti-patterns + pre-merge checklist.
    • Open: GitOps + ArgoCD

20. GitHub Actions CI/CD

    • Reusable workflows (workflow_call): typed inputs/secrets/outputs; thin per-repo callers.
    • Pipeline orchestration (uses + needs), gating, main vs PR pipelines, concurrency.
    • SemVer from conventional commits, automated tag + release.
    • Security gates (dependency review, secret scan, OWASP, Qodana/Sonar), least-privilege permissions, OIDC deploys.
    • Branch + tag rulesets as code, CODEOWNERS, action pinning.
    • Open: GitHub Actions

21. Git Workflow & Best Practices

    • Conventional commits (enforced by commit-lint), atomic commits, branching model.
    • Pull requests (squash, linear history, 2 approvals), rebase discipline, history immutability.
    • Secret hygiene, .gitignore, signing, local hooks.
    • Open: Git Workflow

For Architects

22. Architecture Document Specification

    • 21 mandatory sections (C4, ADR portfolio, STRIDE, NFR, event catalog, risk register).
    • Format-agnostic structural contract.
    • Open: Arch Doc Spec

23. Diagram Catalog

    • Mermaid, PlantUML, Structurizr conventions.
    • Architecture overview, data flows, module structure, pattern catalog.
    • Open: Diagrams

24. LaTeX Architecture Docs (board-grade PDF)

    • When to use LaTeX vs Markdown/HTML.
    • Tectonic / TeX Live / Pandoc bridge.
    • Used by /arch-doc --format=latex for ARB, audit, regulator submissions.
    • Open: LaTeX Architecture Docs

For AI Assistants

25. Claude Code Guide
    • Index + required-reading order + workflow routing.
    • Themed sub-files: ccg-domain-and-ports.md (Steps 1-3), ccg-adapters-and-wiring.md (Steps 4-5), ccg-bugfix-and-testing.md, ccg-reference.md (common tasks, anti-patterns, checklists).
    • Companion command + agent index (/arch-scaffold, /arch-otel, /arch-review, etc.).
    • Open: Claude Code Guide

Project Automation

26. Get Shit Done (GSD)
    • Pipeline: new-project → spec → discuss → plan → execute → verify → ship.
    • 33 specialized agents with wave-based parallelization.
    • 67 skills across 6 namespaces (workflow / review / project / context / ideate / manage).
    • Modes: interactive, semi-auto, quick, fast, autonomous, manager, ultraplan, MVP.
    • Lifecycle: project → milestone → phase → plan → task (atomic commits).
    • Quality gates: code-review, secure-phase, eval-review, ui-review, validate-phase, audit-uat/milestone.
    • Codebase intel: map-codebase, graphify, docs-update, extract-learnings, ingest-docs.
    • Open: GSD Guide

Reading Order

For New Team Members:

1. Resources — verify all project files exist.
2. DDD — understand domain concepts.
3. Hexagonal Architecture — layer structure and patterns.
4. ADR — how decisions are recorded.
5. Clean Code — coding principles.
6. Kotlin Code Style or Java Code Style per language.
7. Spring Boot — framework integration.
8. Testing — quality assurance patterns.
9. Observability — monitoring and tracing.
10. Gradle — build configuration.
11. Liquibase — migration discipline.
12. Security — STRIDE, AuthN/Z, secrets, validation, injection, crypto, logging, audit, compliance.
13. Keycloak — Keycloak topologies (gateway-first vs resource server), role mapping, auth microservice, grant flows, testing.
14. API Design — REST conventions, versioning, error envelope, pagination, idempotency, OpenAPI contract-first.
15. Messaging — transactional outbox, broker selection, envelope, idempotent consumers, schema evolution.
16. API Gateway — KrakenD reference, edge auth/rate-limit/trace-context, mTLS to backends.
17. GitOps + ArgoCD — declarative cluster state, Application/AppProject/ApplicationSet, secrets, progressive delivery.

For AI Assistants (Claude Code, Junie, Copilot, Cursor):

1. Resources — verify resource files; create missing ones.
2. Hexagonal Architecture — hexagonal structure.
   • 2-bis. If the feature publishes events, consumes messages, or touches the outbox, read Messaging BEFORE the messaging section of hexagonal-architecture.md. Messaging is the source of truth for outbox-first; hexagonal-architecture.md defers to it.
3. Scan docs/adr/ for accepted ADRs that constrain the change; ADR before authoring a new one.
4. Claude Code Guide — code generation patterns.
5. Observability — metrics and tracing patterns.
6. Liquibase — before any DB change.
7. Security — before any endpoint, consumer, or sensitive code change.
8. Keycloak — before wiring Keycloak auth, resource-server config, role mapping, or the auth microservice.
9. API Design — before adding or modifying any REST endpoint.
10. Messaging — full reference: outbox, envelope, claim-based dispatch, retry, idempotency, schema evolution. Reference impl: codehuntersio-sdk-event-messaging.
11. API Gateway — before changing edge config, route table, JWT skip-paths, or trace propagation.
12. GitOps + ArgoCD — before adding/modifying any Kubernetes manifest, Application, ApplicationSet, image tag, or sync policy.
13. Reference Kotlin Code Style, Java Code Style, Clean Code, Testing as needed.

For Architects (board deliverable):

1. Arch Doc Spec — 21 mandatory sections.
2. Diagrams — diagram conventions.
3. LaTeX Architecture Docs — PDF generation toolchain.
4. ADR — decision portfolio.

Quick Reference