Skip to main content

System Patterns — ValkyrAI

Architectural Patterns​

  • Codegen-Driven DDD: Domain models, services, and API layers are generated from OpenAPI specs using ThorAPI, enforcing consistency and reducing manual errors.
  • Repository Pattern: All data access is abstracted via repositories, supporting testability and separation of concerns.
  • Composition Over Inheritance: Prefer composable, modular components and services to maximize flexibility and maintainability.
  • Separation of Concerns: Backend, frontend, and codegen templates are clearly separated; business logic is isolated from infrastructure.

Security Patterns​

  • RBAC & ACL: Role-based and object-level access control enforced via Spring Security ACL and custom annotations.
  • SecureField Encryption: Sensitive fields are always encrypted at rest using SecureField (AES-256).
  • Environment-Based Secrets: All secrets and keys are injected via environment variables, never hardcoded or committed.

Testing & Documentation​

  • Test Coverage: Unit tests for business logic, integration tests for APIs, E2E for critical flows. All new features require tests.
  • Documentation: All feature changes must be reflected in /docs and README.md. Changelog entries are mandatory for feature or breaking changes.
  • ADR Process: Major architectural or dependency changes require an Architecture Decision Record in /docs/adr.

Project Conventions​

  • Never Edit Generated Code: All changes to generated code must be made via OpenAPI spec or codegen templates.
  • Update Docs/Changelog: All changes must be documented in the appropriate files.
  • Error Handling: Use the shared error handling pattern in /src/utils/errors.ts for frontend; standard Spring exception handling for backend.
  • Naming: Avoid reserved words and problematic capitalization in OpenAPI specs and code.

Integration Patterns​

  • Generated Clients: Always use generated TypeScript clients and RTK Query slices for API access.
  • Asset Management: Use ContentData and medialink arrays for asset relationships; maintain referential integrity in both backend and frontend.