Summary
The project currently has well-maintained CLAUDE.md files per module and some README.md files, but no central, structured engineering documentation that serves as a reference for human developers — independent of AI tooling.
This issue tracks the creation of a docs/ directory that covers all relevant aspects of working with and contributing to this codebase.
Aspects to cover
Coding Standards
How code should be written across all three languages (Java/Kotlin, TypeScript/React, Python) — naming conventions, code structure, style rules, and error handling patterns.
Code Documentation
When and how to document code: JavaDoc/KDoc for the API, TSDoc for the frontend, Google-style docstrings for the converter, and general Markdown formatting guidelines for all written docs.
Testing Strategy
Testing conventions and structure for each module, the integration testing approach (including the no-DB-mock rule), and coverage expectations.
Architecture & Design Decisions
Architecture Decision Records (ADRs) for key existing decisions (e.g. why Neo4j, why Cognito), REST API design rules, database/graph conventions, and the enforced dependency direction between modules.
Development Workflows
Git branching strategy, PR process, the issue implementation workflow, release process, and hotfix procedure.
Security Guidelines
Secrets management rules, the Cognito/JWT trust chain, relevant OWASP considerations, and dependency security practices.
CI/CD & Environments
Explanation of the GitHub Actions pipelines, what to validate locally before pushing, and the differences between local, test, and prod environments.
Onboarding
A guided path for new developers to set up their environment, understand the repo structure, and make their first contribution.
Templates & Checklists
Reusable templates (PR descriptions, bug reports, feature requests, ADRs, postmortems) and checklists for recurring tasks (pre-commit, code review, new endpoint, security review).
Summary
The project currently has well-maintained
CLAUDE.mdfiles per module and someREADME.mdfiles, but no central, structured engineering documentation that serves as a reference for human developers — independent of AI tooling.This issue tracks the creation of a
docs/directory that covers all relevant aspects of working with and contributing to this codebase.Aspects to cover
Coding Standards
How code should be written across all three languages (Java/Kotlin, TypeScript/React, Python) — naming conventions, code structure, style rules, and error handling patterns.
Code Documentation
When and how to document code: JavaDoc/KDoc for the API, TSDoc for the frontend, Google-style docstrings for the converter, and general Markdown formatting guidelines for all written docs.
Testing Strategy
Testing conventions and structure for each module, the integration testing approach (including the no-DB-mock rule), and coverage expectations.
Architecture & Design Decisions
Architecture Decision Records (ADRs) for key existing decisions (e.g. why Neo4j, why Cognito), REST API design rules, database/graph conventions, and the enforced dependency direction between modules.
Development Workflows
Git branching strategy, PR process, the issue implementation workflow, release process, and hotfix procedure.
Security Guidelines
Secrets management rules, the Cognito/JWT trust chain, relevant OWASP considerations, and dependency security practices.
CI/CD & Environments
Explanation of the GitHub Actions pipelines, what to validate locally before pushing, and the differences between
local,test, andprodenvironments.Onboarding
A guided path for new developers to set up their environment, understand the repo structure, and make their first contribution.
Templates & Checklists
Reusable templates (PR descriptions, bug reports, feature requests, ADRs, postmortems) and checklists for recurring tasks (pre-commit, code review, new endpoint, security review).