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

8b. application.yml Standard

• Hard rules, canonical block order, ${VAR:default} policy, profile documents.
• Secret store (Parameter Store / OpenBao), effective precedence, relaxed binding.
• Actuator hardening, test application.yml, @ConfigurationProperties as the contract, anti-patterns + pre-merge checklist.
• Open: application.yml

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 Mobile Developers

Sections 22-27 apply to React Native / Expo apps. They are the mobile counterparts of the JVM guides above: same architectural rules, different language and adapters. Do not apply the JVM sections literally to a mobile codebase, and do not apply these to a backend service.

22. Mobile Architecture (Hexagonal in React Native)

    • When hexagonal is warranted vs Feature-Sliced Design; decision matrix.
    • Layer placement rules, folder layout, ports, adapters, decorators, DI container.
    • Parse-don’t-validate at every boundary (HTTP, storage, deep links, push).
    • Offline + local outbox, monorepo layout, ESLint boundary enforcement (the ArchUnit equivalent).
    • Companion commands: /mobile-init-project, /mobile-scaffold-feature, /mobile-add-usecase, /mobile-add-adapter.
    • Open: Mobile Architecture

23. React Native

    • Runtime baseline (New Architecture), Expo-by-default and when bare RN needs an ADR.
    • Library selection matrix, Expo Router, HTTP client, environment/variants.
    • Server state vs client state — TanStack Query vs Zustand, the most common mistake.
    • Performance: lists, re-renders, animation, startup, profiling.
    • Open: React Native

24. TypeScript Code Style

    • Strict compiler flags, type vs interface, immutability, branded types.
    • Discriminated-union domain errors, Result<T, E> over throw, banned constructs.
    • Open: TypeScript Code Style

25. Mobile Testing Strategy

    • Pyramid mapped to layers; fakes over mocks; determinism via Clock / IdGenerator.
    • Jest/Vitest, React Native Testing Library, MSW, Maestro E2E, coverage gates.
    • Companion command: /mobile-add-test.
    • Open: Mobile Testing

26. Mobile UI

    • Styling engine selection (Unistyles / NativeWind / Tamagui) and why a component kit fights a custom identity.
    • Design tokens (two-tier), theming and dark mode, component tiers.
    • The four screen states, accessibility gates, i18n, layout, interaction, motion.
    • Companion commands: /mobile-init-project, /mobile-add-screen.
    • Open: Mobile UI

26b. Tailwind CSS v4 (web + mobile)

• v4 mental model: @theme namespaces, no tailwind.config.js; namespace shadowing (max-w-* broken).
• @source in a monorepo, verify-don’t-assume probe recipe, class-based dark mode.
• Adopting a paid component kit (Tailwind Plus / Catalyst), Module Federation, opacity-* contrast trap.
• Open: Tailwind CSS

27. Mobile Security & Release
    • Security: the attacker owns the device; SecureStore vs MMKV, no secrets in the bundle, PKCE, deep links as an unauthenticated entry point, pinning, logging.
    • Release: EAS Build/Submit, runtimeVersion fingerprint policy, OTA limits and store policy, gradual rollout, crash-free sessions, rollback asymmetry.
    • Open: Mobile Security · Mobile Release

For Architects

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

28b. Functional Specification (anatomy)

• Anatomy of a module functional spec: metadata, identifier guide, scope + out-of-scope.
• Stable identifiers (letter suffixes, never renumber), verifiable acceptance criteria.
• Traceability matrix with Origin / Source; responsibility matrix (requests / validates / approves).
• Assumptions (S-) vs blockers (B-).
• Open: Functional Spec

28c. Specification Traceability (external spec → code)

• When the functional spec comes from outside: prove criterion by criterion what is met.
• Coverage matrix, verdicts including covered but inert; six audit rules.
• Version delta with five buckets; gaps with owner — the input to task breakdown.
• Open: Spec Traceability

29. Diagram Catalog

    • Mermaid, PlantUML, Structurizr conventions.
    • Architecture overview, data flows, module structure, pattern catalog.
    • Themed sub-files: arch-overview.md, ports-and-commands.md, data-flows.md, patterns-catalog.md, c4-diagrams.md (package, runtime, outbox event flow), best-practices.md (per-layer rules, roadmap, troubleshooting).
    • Open: Diagrams

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

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

31b. AI-Native SDLC (spine — read before the two below)

• Artifact chain intent.md → spec.md → plan.md → diff → PR → production → intent.md.
• Stage-by-stage map of what exists here vs what is missing; where each control belongs.
• Process metrics (leading / lagging), the Maintain loop (bands.yaml), REVIEW.md policy, roadmap.
• Open: AI-Native SDLC

31c. Evals

• Regression tests for agent configuration: CLAUDE.md, rules, skills, hooks.
• Case format, runner (~/.claude/evals/run.sh), CI gate, incident→eval rule, starter battery.
• Open: Evals

31d. Hooks

• Build hooks vs deploy approval gates; the three control tiers and when to escalate.
• Current inventory classified, open gaps (attribution gate, control-path protection), governance.
• Open: Hooks

Project Automation

32. 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; application.yml for the config file itself.
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 Mobile (React Native / Expo):

1. Mobile Architecture — decide hexagonal vs FSD first, then layer placement.
2. TypeScript Code Style — strict flags, branded types, Result over throw.
3. React Native — Expo setup, library matrix, server vs client state.
4. Mobile UI — tokens, four screen states, accessibility.
5. Mobile Testing — before writing the feature, not after.
6. Mobile Security — before any storage, auth, or deep-link work.
7. Mobile Release — before the first build, not before the first release.
8. ADR — architecture, library and offline-strategy choices are all ADRs.

For Architects (board deliverable): 0. Functional Spec / Spec Traceability — when the module spec exists (or arrives from outside) before any architecture work.

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

Quick Reference