Sangeetha-Grantha

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

Sangeetha Grantha: Architecture Evaluation & Scaling Strategy

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

Status: Evaluation | Version: 1.0 | Date: 2026-01-14
Evaluator: Architecture Review
Target Scale: Millions of users worldwide

Executive Summary

Sangeetha Grantha is a well-architected, domain-driven application with strong musicological modeling and clean separation of concerns. The current architecture is production-ready for small to medium scale (thousands of concurrent users), but requires significant enhancements to scale to millions of users worldwide.

Key Strengths:

Critical Gaps for Global Scale:

1. Current Architecture Analysis

1.1 System Components

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Mobile App  │     │ Admin Web   │     │   Public    │
│  (KMM)      │     │  (React)    │     │   Web?      │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┴───────────────────┘
                          │
                  ┌───────▼───────┐
                  │  Ktor Backend │
                  │  (Single Pod) │
                  └───────┬───────┘
                          │
                  ┌───────▼───────┐
                  │  PostgreSQL   │
                  │  (Primary)    │
                  └───────────────┘

Current Scale Assumptions:

1.2 Performance Characteristics

Current Optimizations (Good):

Bottlenecks Identified:

  1. Database Connection Pool: 10 connections is insufficient for high concurrency
  2. No Query Result Caching: Repeated searches hit database every time
  3. No CDN: Static assets and API responses served from origin
  4. Synchronous AI Calls: Gemini API calls block request threads
  5. Single Database: No read scaling capability
  6. No Search Index: Full-text search on PostgreSQL only (will degrade)

2. Scaling Challenges & Solutions

2.1 Database Layer

Current State

Scaling Strategy

**Phase 1: Connection Pool Optimization**
// Current: maxPoolSize = 10
// Recommended for scale:
maxPoolSize = 50-100 (per instance)
minIdle = 10-20
connectionTimeout = 30_000
maxLifetime = 1_800_000

Phase 2: Read Replicas

Primary (Write) ──┐
                  ├──> Read Replica 1 (US-East)
                  ├──> Read Replica 2 (EU-West)
                  └──> Read Replica 3 (AP-South)

Implementation:

Phase 3: Connection Pooling Service (PgBouncer)

Phase 4: Database Sharding (Future)

2.2 Caching Layer

Current State

Scaling Strategy

Phase 1: Application-Level Caching (Redis)

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Ktor    │────▶│  Redis   │────▶│PostgreSQL│
│ Backend  │     │  Cache   │     │          │
└──────────┘     └──────────┘     └──────────┘

Cache Strategy:

  1. Reference Data (TTL: 1 hour)
    • Composers, Ragas, Talas, Deities, Temples
    • Rarely changes, high read frequency
    • Cache key: ref:composers, ref:ragas, etc.
  2. Krithi Detail (TTL: 5 minutes)
    • Full krithi with sections, lyrics, notation
    • Cache key: krithi:{id}
    • Invalidate on update/publish
  3. Search Results (TTL: 1 minute)
    • Paginated search results
    • Cache key: search:{hash(query+params)}
    • Short TTL due to frequent updates
  4. Public API Responses (TTL: 5 minutes)
    • Entire JSON response for /v1/krithis/{id}
    • Reduces database load significantly
**Implementation:**
// Add Redis client (e.g., Lettuce or Jedis)
class CacheService(private val redis: RedisClient) {
    suspend fun <T> getOrSet(
        key: String,
        ttl: Duration,
        fetch: suspend () -> T
    ): T {
        val cached = redis.get(key)
        if (cached != null) return deserialize(cached)
        val value = fetch()
        redis.setex(key, ttl.seconds, serialize(value))
        return value
    }
}

Phase 2: CDN for Static Assets

Phase 3: HTTP Response Caching

2.3 Search & Indexing

Current State

Scaling Strategy

Phase 1: PostgreSQL Full-Text Search Enhancement

Phase 2: Dedicated Search Engine (Elasticsearch/OpenSearch)

┌──────────┐     ┌──────────────┐
│  Ktor    │────▶│ Elasticsearch│
│ Backend  │     │  (Search)    │
└──────────┘     └──────────────┘

Benefits:

Implementation:

Alternative: PostgreSQL with pg_trgm + Materialized Views

2.4 API Layer Scaling

Current State

Scaling Strategy

Phase 1: Horizontal Scaling

                    ┌──────────┐
                    │   LB     │
                    │ (Nginx/  │
                    │  ALB)    │
                    └────┬─────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼────┐      ┌────▼────┐      ┌────▼────┐
   │ Ktor 1  │      │ Ktor 2  │      │ Ktor 3  │
   └─────────┘      └─────────┘      └─────────┘

Implementation:

**Phase 2: Rate Limiting**
// Add rate limiting plugin (e.g., Bucket4j)
install(RateLimiter) {
    rateLimiter = RateLimiter.create(100.0) // 100 req/sec per IP
    // Or use Redis-based distributed rate limiting
}

Rate Limits:

Phase 3: API Gateway (Optional)

2.5 Asynchronous Operations

Current State

Scaling Strategy

Phase 1: Message Queue (RabbitMQ/AWS SQS)

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Ktor    │────▶│  Queue   │────▶│  Worker  │
│ Backend  │     │ (SQS)    │     │ (Gemini) │
└──────────┘     └──────────┘     └──────────┘

Use Cases:

Implementation: // Async job submission suspend fun transliterateAsync(content: String): JobId { val job = TransliterationJob(content) queue.enqueue(job) return job.id }

// Worker processes jobs
class TransliterationWorker {
    suspend fun process(job: TransliterationJob) {
        val result = geminiClient.transliterate(job.content)
        // Update database or cache
    }
}

Phase 2: Background Job Framework

2.6 Geographic Distribution

Current State

Scaling Strategy

Phase 1: Multi-Region Deployment

US-East (Primary) ──┐
                    ├──> Database Replication
EU-West ────────────┤
                    └──> AP-South

Architecture:

Phase 2: Edge Computing

2.7 Monitoring & Observability

Current State

Scaling Strategy

Phase 1: Application Metrics

Phase 2: Distributed Tracing

Phase 3: Alerting

3. Implementation Roadmap

Phase 1: Foundation (Months 1-2)

Priority: Critical

  1. Connection Pool Tuning
    • Increase HikariCP pool to 50-100
    • Add connection pool monitoring
  2. Redis Caching
    • Deploy Redis cluster
    • Implement cache service
    • Cache reference data and krithi details
  3. Rate Limiting
    • Add rate limiting middleware
    • Protect public endpoints
  4. CDN Setup
    • Deploy static assets to CDN
    • Cache public API responses

Expected Impact:

Phase 2: Scaling (Months 3-4)

Priority: High

  1. Read Replicas
    • Set up PostgreSQL read replicas
    • Route read queries to replicas
  2. Horizontal Scaling
    • Deploy multiple Ktor instances
    • Add load balancer
  3. Search Engine
    • Deploy Elasticsearch/OpenSearch
    • Index krithis asynchronously
    • Migrate search endpoints

Expected Impact:

Phase 3: Advanced (Months 5-6)

Priority: Medium

  1. Message Queue
    • Deploy RabbitMQ/AWS SQS
    • Move AI operations to async
  2. Multi-Region
    • Deploy to 2-3 regions
    • Set up database replication
  3. Advanced Monitoring
    • Add distributed tracing
    • Set up alerting

Expected Impact:

4. Cost Estimation (Rough)

Current (Single Region, Small Scale)

Phase 1 (With Caching)

Phase 2 (With Read Replicas)

Phase 3 (Multi-Region)

5. Risk Assessment

High Risk

  1. Database Bottleneck: Single database will fail under load
    • Mitigation: Read replicas + caching (Phase 1-2)
  2. No Rate Limiting: Vulnerable to DDoS
    • Mitigation: Implement rate limiting (Phase 1)
  3. Synchronous AI Calls: Blocks request threads
    • Mitigation: Move to async queue (Phase 3)

Medium Risk

  1. Search Performance: PostgreSQL search will degrade
    • Mitigation: Elasticsearch (Phase 2)
  2. Single Point of Failure: No redundancy
    • Mitigation: Multi-instance + read replicas (Phase 2)

Low Risk

  1. Geographic Latency: Acceptable for v1
    • Mitigation: Multi-region (Phase 3)

6. Recommendations Summary

Immediate Actions (Before Scale)

  1. ✅ Add Redis caching for reference data and krithi details
  2. ✅ Increase connection pool to 50-100
  3. ✅ Add rate limiting on public endpoints
  4. ✅ Deploy CDN for static assets

Short-Term (3-6 months)

  1. ✅ Add read replicas for database scaling
  2. ✅ Deploy Elasticsearch for search
  3. ✅ Horizontal scaling (multiple Ktor instances)
  4. ✅ Message queue for async operations

Long-Term (6-12 months)

  1. ✅ Multi-region deployment
  2. ✅ Advanced monitoring and alerting
  3. ✅ Database sharding (if needed)

7. Architecture Decision Records (ADRs) Needed

  1. ADR-007: Caching Strategy (Redis vs Memcached vs In-Memory)
  2. ADR-008: Search Engine (Elasticsearch vs PostgreSQL FTS vs Algolia)
  3. ADR-009: Message Queue (RabbitMQ vs AWS SQS vs Kafka)
  4. ADR-010: Multi-Region Strategy (Active-Passive vs Active-Active)
  5. ADR-011: CDN Provider (CloudFront vs Cloudflare vs Fastly)

8. Conclusion

Sangeetha Grantha has a solid foundation with clean architecture and modern technologies. To scale to millions of users worldwide, the following are critical:

  1. Caching layer (Redis) - Reduces database load by 50-70%
  2. Read replicas - Enables horizontal read scaling
  3. CDN - Reduces latency and bandwidth costs
  4. Rate limiting - Protects against abuse
  5. Search engine - Maintains fast search at scale
  6. Horizontal scaling - Supports high concurrency
  7. Async operations - Prevents blocking on AI calls

With these enhancements, the system can scale from thousands to millions of users while maintaining the musicological rigor and editorial governance that makes Sangeetha Grantha valuable.

Estimated Timeline: 6-12 months for full scaling implementation
Estimated Cost: $1,250-7,500/month depending on scale
Expected Capacity: 1M+ concurrent users with proper implementation

Section index · Documentation home · Feature status