Sangeetha-Grantha

Metadata Value
Status Active
Version 1.2.0
Last Updated 2026-09-10
Author Sangeetha Grantha Team
Document Type Current guide

Mutation handling and audit boundaries

Backend routes parse requests and delegate to services. Services coordinate domain decisions; repositories execute SQL inside DatabaseFactory.dbQuery. Return explicit serializable DTOs across those boundaries.

A controlled mutation

  1. Authenticate and enforce the required server-side role.
  2. Validate identifiers, payload fields, ownership and operation state.
  3. Resolve domain identity using canonical references and evidence.
  4. Persist the intended changes in the appropriate transaction boundary.
  5. Record the audit event and, for accepted canon changes, the required revision/provenance.
  6. Return the actual persisted result and a meaningful failure when the operation cannot complete.

Do not confuse a requested invariant with an automatic guarantee across independently called repositories. Review the real service transaction boundary when adding multi-step changes. Use tests to establish failure atomicity where required.

Corpus-specific rules

Lyric sections belong to a composition and a specific variant. Ordered raga membership belongs in krithi_ragas, not only a primary foreign key. Unknown raga identity requires controlled resolution. Accepted source corrections use extraction/reingestion/curation rather than new one-off corpus SQL migrations.

Versioned canon records historical section text; audit logging records mutation events. Both differ from the public current-state reader model.

Source references

Section index · Documentation home · Feature status