Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (28 loc) · 4 KB

AGENTS.md

File metadata and controls

36 lines (28 loc) · 4 KB
Raw

Capsule

Code Style

  • Self-validation: Most if not all code should be modular, reusable, and testable. The code that requires human review and manual testing should be minimal and focused on user facing features. All critical code must be primarily covered by complete and automated tests.
  • Contract-driven development: Define the interfaces and data structures first, along with all test cases, before implementing the actual logic.
  • Cohesion: All code should be split into cohesive modules that have a single responsibility and clear interfaces. Encapsulate unnecessary details.
  • Minimalism: Choose to use a dependency if it reduces the scope of testing and quantity of code and as long as it does not compromise on performance and required capabilities.
  • Traceability: all critical processes are verbosely logged so it is clear what happened after the fact and recovery can be feasible. Use INFO logs where necessary and DEBUG,TRACE aggressively for all critical processes. Logs should be structured and easily queryable. Instrument hot paths (e.g. major functions) for performance monitoring and debugging in production.
  • Mocking: Use mocks for all external dependencies and critical internal processes. This allows us to have deterministic tests and easily simulate edge cases and failure scenarios that are hard to reproduce with real dependencies. Do not try to wire up two incomplete complex systems to mock each other.
  • Linting and formatting is setup to be strict. Pre-commit and pre-push hooks are configured so you won't be able to push code that doesn't meet the standards.

Dependencies

  • Datetime: jiff, never chrono — chrono exists only as the sea-orm column type inside capsule-cli/entity (convert at the entity boundary) and review-only server code.
  • Errors: thiserror in libraries, eyre/color-eyre in binaries; no anyhow.
  • Logging: tracing, never the log facade in new code.
  • TLS: rustls only; never native-tls/openssl.
  • Identifiers: UUIDv7 for new ids; UUIDv4 only where creation time must not leak.
  • The canonical table (all platforms, exceptions, rationale) is the Dependencies design doc — add a row there before introducing a dependency for a new domain.

Internationalization

  • No hardcoded user-facing strings. Every translatable string is a key in the canonical catalogs under locales/ (ICU MessageFormat). Add the key there, not inline in app code.
  • After editing locales/, run mise run i18n to regenerate the per-platform files (Rust bundle, web JSON, Android strings.xml, iOS .xcstrings). Generated files are committed and carry a "do not edit by hand" banner; mise run i18n-check (part of check-rust) fails on drift.
  • Keys use dotted namespaces (area.subarea.name). Server errors carry a stable code from the error.* namespace (referenced via capsule_i18n::error_codes); clients localize the code while the English detail message stays English.
  • See the i18n design doc for the full contract and locales/README.md for the contributor workflow.

Rust Architecture Decisions

  • The public server surface is Kynos REST/OpenAPI only. Do not reintroduce Salvo, GraphQL, or gRPC.
  • Generate clients with Spargen from the checked-in Kynos OpenAPI contract. Do not use Progenitor.
  • Rawshift owns media decoding, metadata extraction, and derivative generation. Capsule imports Chromahash directly only after its v1 release; Rawshift must not wrap it.
  • Blob storage and resumable encrypted upload remain Capsule-owned behind narrow, arbitrary-backend ports. Do not add object_store or generic CAS/transfer crates without revisiting the security contract.
  • Keep authentication state and upload-session state as separate Capsule ports with PostgreSQL, redis-rs, and in-memory adapters. Do not introduce a generic TTL/CAS abstraction.
  • legacy-review/ is non-buildable reference material. Restore code only after defining its contract and automated tests against the decisions above.