Sangeetha-Grantha

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

🤖 AI & Vibe Coding References

---

[!NOTE] Design/reference material: this page may include proposals or earlier implementation assumptions. Use implemented AI capabilities for implemented behavior and current operating steps.

---

This document provides essential references for AI coding assistants (VS Code Copilot, Codex, Cursor, Google Antigravity) working with the Sangeetha Grantha codebase.

---

Product & Requirements

• Sangita Grantha PRD - Primary product requirements
• Domain Model - Core entity relationships and data structures
• Glossary - Domain terminology

---

Architecture & Design

• Backend Architecture - Ktor patterns, service layer, DAL structure
• Mutation Handlers - Audit logging and mutation patterns
• Security Requirements - Auth, RBAC, and security patterns
• Tech Stack - Complete technology inventory

---

API & Integration

• OpenAPI Spec (Deleted) - Complete API contract
• API Contract - API design patterns and conventions
• UI ↔ API Mapping - Frontend-backend integration

---

Database

• Schema Overview - PostgreSQL schema documentation
• Migrations - Migration strategy (Flyway, the only engine — see ADR-013)
• Audit Log - Audit trail requirements

---

Frontend

• Admin Web PRD - Admin console requirements
• React Admin Web Specs - Frontend architecture

---

Development Workflow

• Sangita CLI README - Database management and dev commands
• Steel-thread Implementation - Core workflows

---

Key Patterns to Follow

Database Operations

• ✅ Use DatabaseFactory.dbQuery { } for all database operations
• ✅ All mutations must write to AUDIT_LOG table
• ✅ Flyway is the only migration engine (ADR-013) - run via make migrate / make db-reset; never Liquibase, ad-hoc SQL executors, or custom runners. The Python db-migrate tool and the Kotlin test-side MigrationRunner are retired.

Dependency Management

• ✅ Use gradle/libs.versions.toml for dependency management
• ✅ Reference version catalog in build files

Code Organization

• ✅ Keep DTOs in modules/shared/domain for cross-platform use
• ✅ Use kotlinx.serialization for DTOs
• ✅ Use kotlinx.datetime.Instant (not Java date/time classes)
• ✅ Use kotlin.uuid.Uuid for IDs

Backend Patterns

• ✅ Keep routes thin; delegate to services/repositories
• ✅ Return explicit DTOs, not Exposed entity objects
• ✅ Use suspend functions consistently
• ✅ Error handling: sealed results or nullable returns (avoid exceptions unless necessary)

Frontend Patterns

• ✅ Use function components with explicit TypeScript types
• ✅ Avoid any type; prefer ReactNode, PropsWithChildren, discriminated unions
• ✅ Use Tailwind utility classes for styling
• ✅ Keep components small and composable

---

Conductor & AI Change Tracking (For Assistants)

When proposing or implementing any changes to the codebase, assistants must follow Conductor tracking rules:

• Always register a Track for any new AI feature or significant enhancement:
  • Add/ensure a row exists in conductor/tracks.md with a unique Track ID, name, and status.
  • Example: TRACK-002 | Gemini Transliteration Hardening | In Progress.
• Always create or update a Track detail file:
  • File path: conductor/tracks/TRACK-XXX-some-slug.md.
  • Use TRACK-001-bulk-import-krithis.md as the canonical template (Goal, Context, Architecture Overview, Phased Plan, Progress Log, Technical Details).
• Tie code/docs changes to Tracks:
  • When editing AI-related code or docs (anything under application_documentation/09-ai/ or Gemini-related services), update the corresponding TRACK file’s Progress Log.
  • Ensure the work described in AI docs (e.g., new service, endpoint, or workflow) cites the relevant TRACK-XXX where appropriate.

Conductor resources:

• conductor/index.md
• conductor/tracks.md
• conductor/tracks/TRACK-001-bulk-import-krithis.md

Quick Reference Commands

# Database management
make migrate      # Run pending migrations
make db-reset     # Reset database (drop → create → migrate → seed)

# Development workflow
make dev          # Start full stack (DB + Backend + Frontend + Extraction)
make dev-down     # Stop all services

# Testing
make test         # Run backend tests
make test-frontend  # Run frontend tests

---

Important Constraints

• ✅ Flyway is the only migration engine (ADR-013) - run via make migrate / make db-reset; never Liquibase or custom migration runners
• ✅ Always reference version catalog in build files
• ✅ Keep changes minimal and surgical
• ✅ Follow existing patterns in the codebase
• ✅ Use DatabaseFactory.dbQuery for all DB operations

---

For the complete documentation index, see README.md.

---

Section index · Documentation home · Feature status