Project Rules
Single source of truth for all project constraints. CLAUDE.md, CODEX.md, and module-level docs index into this file.
Meta
- Add rule: Requires Human approval. Include: ID, statement, source.
- Modify rule: State reason + link to the failure that triggered the change.
- Deprecate rule: Mark
deprecatedwith date and replacement. Remove after 30 days. - Feedback: Agents record proposed rules in § Feedback. Human promotes to formal rules.
- Inheritance: Module-level CLAUDE.md inherits all rules here. Modules only add, never override.
Golden Rules
Hard constraints. Violation causes systemic failure.
| ID | Rule | Source |
|---|---|---|
| G001 | {module}/db/schema/*.sql is the sole hand-maintained source of database structure. All code-layer artifacts are derived. | DB Runbook |
| G002 | Application does not manage schema. No Flyway, no Hibernate DDL-auto, no migration frameworks. Ops executes reviewed changelog SQL. | Migration Strategy |
| G003 | persistence/generated/ is derived output. Never hand-edit. Regenerate from schema via generate-jooq.py. | Session 2026-03-31 |
| G004 | Schema changes are atomic: {module}/db/schema/*.sql + {module}/db/changelog/ + regenerated Java code committed together. | Migration Strategy |
| G005 | Cross-agent review: a different agent always reviews. Same agent reviewing own output is not review. | SLX governance |
| G006 | Changelog entries are append-only. Never modify or delete a published entry. | Migration Strategy Rule 2 |
| G007 | Branch promotions follow dev → test → alpha → product. No skip-level promotions. product requires manual release approval. | CONTRIBUTING.md § Branch Policy |
Architecture
Key decisions. Details in docs/adr/.
| ID | Decision | ADR |
|---|---|---|
| A001 | CQRS controllers: *CommandController (writes) + *QueryController (reads) | ADR-0011 |
| A002 | POST body for resource operations, not path variables | ADR-0005 |
| A003 | Workspace context via X-Workspace-Context header | ADR-0012 |
| A004 | Deny-by-default gateway chain routing | ADR-0002 |
| A005 | Portal x Chain matrix as access control model | ADR-0009 |
| A006 | Handler pattern: complex operations in dedicated handler classes | CONTRIBUTING.md |
| A018 | Orchestration-Capability separation: UseCase (per-portal) assembles ALL parameters; Capability/Service (shared) receives complete params and executes — no defaults, no context reading, no assumptions about caller | Session 2026-04-01 |
| A007 | Event-driven: publish Spring application events for async side effects | CONTRIBUTING.md |
| A008 | Multi-tenant: all business data scoped to workspace + portal type | CONTRIBUTING.md |
| A009 | Lockstep versioning from root POM. Module-local version only for intentional divergence. | ADR-0001 |
| A010 | Per-session JWT signing: one HMAC secret per authenticated session, stored in Redis. Global secret rotation not needed. | ADR-0003 |
| A011 | Domain isolation: Repository classes only accessible within their own domain | PlatformArchitectureTest R1 |
| A012 | Domain isolation: Exception classes only accessible within own domain or shared | PlatformArchitectureTest R2 |
| A013 | QueryPort read-only: @QueryPort classes may only declare find/exists/count/get/has/is methods | PlatformArchitectureTest R4 |
| A014 | Event immutability: no setter methods on *Event classes | PlatformArchitectureTest R5 |
| A015 | No ApiResponse<Page<T>> return type in controllers; use SlxPage wrapper | PlatformArchitectureTest R6 |
| A016 | Portal isolation: application.shared package is forbidden; orchestration must be portal-isolated | PlatformArchitectureTest R9 |
| A017 | DTO boundary: controllers must not expose entity types in return types; use DTOs | DtoExposureArchTest |
Workspace-scoped ADRs (ADR-0004, 0006, 0007, 0008, 0010, 0013) apply across repos and are not tracked here.
Anti-regression ArchUnit rules (R11–R15) guard against reintroducing removed legacy code. See
PlatformArchitectureTest.javafor details. These are temporary and will be removed as legacy cleanup completes.
Database
Governed by db/. Key points:
- SSoT:
{module}/db/schema/**/*.sql— one file per table - Change process: Update schema → write changelog → ops executes. See Migration Strategy.
- Persistence layer: jOOQ DSL for type-safe queries. Generated from schema, not hand-written.
JdbcTemplate/NamedParameterJdbcTemplateare banned (ArchUnit R16 + CI guard). Historical references to Flyway or JdbcTemplate belong only indocs/archive/. - Codegen tool:
generate-jooq.pygenerates jOOQ table classes fromslaunchx-app-prometheus/db/schema/*.sql. No jOOQ codegen plugin, no DDLDatabase, no JDBC connection at build time. - Module structure: Persistence layer lives in
slaunchx-app-prometheus(com.slaunchx.core.persistence.*), not as a separate infra module. - Categories:
01-api-auththrough14-file-storage. See Schema Convention. - Formatting: Follow Schema Formatting Guide.
Testing
Two-layer standard. See Testing Standard for full specification.
- Layer 1 — Unit Test: In this repo,
src/test/, pure JVM + Mockito, zero Docker. Run:scripts/test-unit.sh. - Layer 2 — Simulation Test: In
slaunchx-backend-simulation-testrepo, Docker full-stack, real API calls. Run:scripts/run-simulation.sh. - Boundary: If it needs real DB/Redis/MQ → Layer 2. If pure logic → Layer 1.
- Prohibited in this repo:
@SpringBootTest,TestContainers, real JDBC/Redis connections insrc/test/. - Existing
*IntegrationTest.java/*E2ETest.javaare deprecated — will migrate to simulation-test.
Code
Governed by CONTRIBUTING.md. Key points:
- Java 21, Spring Boot 3.5.x
google-java-formatenforced via Spotless (mvn spotless:check)- Tests required. Coverage >= 90% (JaCoCo)
- Conventional commits in English (
feat:,fix:,docs:,test:,chore:,refactor:) - Branch ladder:
dev → test → alpha → product. No skip-level promotions. - Versioning: lockstep from root POM. See Versioning Policy.
@AutoConfigurationis for library JARs only. App-internal config classes use@Configuration.- YAML frontmatter required on all new documentation files (title, owner, scope, status, last_reviewed, review_cycle_days).
- Active plans, specs, tasks, and audits must not reintroduce legacy Flyway or JdbcTemplate guidance; keep any historical discussion in
docs/archive/only.
Feedback
Proposals from execution sessions. Human reviews and promotes to formal rules.
| Date | Proposal | Source | Status |
|---|---|---|---|
| 2026-03-31 | jOOQ codegen should use custom tool (generate-jooq.py) from {module}/db/schema/*.sql, not jOOQ codegen plugin or DDLDatabase | jOOQ migration session | promoted 2026-03-31 → § Database |
| 2026-03-31 | infra-jooq module should be dissolved into slaunchx-app-prometheus as persistence layer (com.slaunchx.core.persistence.*) | jOOQ migration session | promoted 2026-03-31 → § Database |
| 2026-03-31 | @AutoConfiguration → @Configuration for in-app config classes (not library JARs) | jOOQ migration session | promoted 2026-03-31 → § Code |
| 2026-03-31 | slaunchx-infra-jdbc has zero references and should be removed | jOOQ migration session | LANDED 2026-03-31 — module removed |
| 2026-03-31 | JdbcTemplate/NamedParameterJdbcTemplate banned. jOOQ DSL is the only persistence API. Enforced by ArchUnit R16 + CI guard. | Phase 5 governance | promoted 2026-03-31 → § Database |
| 2026-03-31 | All 48 repository impls + 6 sandbox repos + 2 services migrated from JdbcTemplate to jOOQ DSL. Deprecated JDBC impls deleted. | Phase 5 cleanup | LANDED 2026-03-31 |