Skip to content

Latest commit

 

History

History
129 lines (101 loc) · 4.42 KB

getting-started.md

File metadata and controls

129 lines (101 loc) · 4.42 KB
Metadata Value
Status Active
Version 1.1.0
Last Updated 2026-03-10
Author Sangeetha Grantha Team

Getting Started with Sangita Grantha

Welcome to the Sangita Grantha project. This document provides a comprehensive guide for new developers and contributors to set up their local development environment and understand our core workflows.

1. Project Overview

Sangita Grantha is the authoritative "System of Record" for Carnatic compositions. It is designed for longevity, musicological integrity, and high-performance access.

For current toolchain and library versions, see Current Versions.

2. Prerequisites

Ensure you have the following installed on your system:

  • mise: Our tool version manager (replaces asdf, nvm, etc.).
  • Docker & Docker Compose: For running the full dev stack (DB, backend, frontend, extraction).
  • Python 3.11+: For the db-migrate migration tool and extraction worker.
  • Bun: For frontend package management and building.
  • JDK 25 (Temurin): For Kotlin and Android development. (See Current Versions)
  • Android Studio / Xcode: For mobile development.

3. Local Environment Setup

Follow these steps to get your environment ready:

3.1 Tooling Installation

Run the following command to install the required tool versions managed by mise:

mise install

3.2 Database Setup

We use Docker Compose to run PostgreSQL. Migrations are managed by the Python db-migrate tool:

# Full stack start (DB + Backend + Frontend + Extraction)
make dev

# Or database only
make db

# Reset DB (drop → create → migrate → seed)
make db-reset

3.3 Frontend Dependencies

Install dependencies for the admin web module using bun:

cd modules/frontend/sangita-admin-web
bun install

4. Development Workflow

4.1 Running the Application

  • Full Dev Stack (recommended):
  make dev          # Docker Compose: DB + Backend + Frontend + Extraction
  make dev-down     # Stop all services
  • Backend only:
  ./gradlew :modules:backend:api:run
  • Frontend only:
  cd modules/frontend/sangita-admin-web
  bun run dev
  • Database Migrations:
  make migrate      # Run pending migrations
  make db-reset     # Drop → create → migrate → seed

4.2 The Conductor System

All work MUST be tracked via the Conductor system located in the conductor/ directory.

  1. Check conductor/tracks.md for active tracks.
  2. If starting a new task, create a track file in conductor/tracks/.
  3. Follow the implementation plan defined in your track.

4.3 Database Migrations

NEVER use Flyway or standard SQL executors for schema changes.

  • All migrations live in database/migrations/.
  • Run migrations via: make migrate
  • Reset the DB (Drop + Create + Migrate + Seed) via: make db-reset
  • Migration tool: Python db-migrate in tools/db-migrate/

5. Coding Standards & Mandates

5.1 Backend (Kotlin)

  • Result Pattern: Always use Result<T, E> for service layer returns. No exceptions for domain logic.
  • DTO Separation: Never leak Exposed DAO entities to the API layer. Map to @Serializable DTOs in modules/shared/domain.
  • Database Access: Use DatabaseFactory.dbQuery { ... }.

5.2 Frontend (React/TS)

  • Strict TypeScript: No any. Use strict interfaces.
  • State Management: Use tanstack-query for data fetching.

5.3 Commit Policy

Every commit message MUST include a reference to the relevant specification:

feat: implement bulk import parser

Ref: application_documentation/01-requirements/features/bulk-import/01-strategy/csv-import-strategy.md

6. Project Structure

  • application_documentation/: High-level requirements, architecture, and API specs.
  • conductor/: Active development tracks and plans.
  • database/migrations/: SQL migration files.
  • modules/backend/: Ktor API and services.
  • modules/frontend/sangita-admin-web/: React admin interface.
  • modules/shared/domain/: KMP module with shared DTOs and logic.
  • tools/db-migrate/: Python migration tool.
  • tools/krithi-extract-enrich-worker/: Python extraction & enrichment worker.

7. Useful Links