Developer Documentation

Feature-specific developer documentation for the Kulcare platform.

StructureCopy Anchor Link

Each feature should have its own folder with a README.md containing:

[feature-name]/
  README.md      # Main documentation
  api.md         # API details (optional)
  diagrams/      # Architecture diagrams (optional)

Required SectionsCopy Anchor Link

Every feature doc must include:

1. Overview - Purpose, responsibilities, key functionality, when to use
2. Technical Architecture - Core components, data flow, key classes/functions
3. API Reference - Public interfaces, important methods, usage examples
4. Dependencies - Internal and external dependencies
5. Configuration - Environment variables, feature flags, runtime config
6. Common Tasks - Setup instructions, development workflows, debugging tips
7. Testing - Unit test approach, integration points, mocking strategies

Feature CategoriesCopy Anchor Link

• Frontend Apps: shell, cms, growth, connect, reports, hospital, admin
• Frontend Packages: api-client, auth-identity, ui-kit, localization, shared-services
• Backend Domains: clinical, identity, billing, catalog, inventory, growth, reference, audit, connect, integration

New backend work belongs in backend/domains/. Deprecated backend modules are not implementation references or dependencies for new features.

Adding a New Feature DocCopy Anchor Link

# [Feature Name]

## Overview
- Purpose and responsibilities
- Key functionality
- When to use this feature

## Technical Architecture
- Core components and their interactions
- Data flow diagrams (Mermaid)
- Key classes/functions

## API Reference
- Public interfaces/exports
- Important methods and signatures
- Usage examples

## Dependencies
- Internal dependencies (other features/packages)
- External libraries
- Version requirements

## Configuration
- Environment variables
- Feature flags
- Runtime configuration

## Common Tasks
- Setup instructions
- Development workflows
- Debugging tips

## Testing
- Unit test approach
- Integration points
- Mocking strategies

Cross-cutting topicsCopy Anchor Link

• Software pattern review: required phase-start and pre-merge architecture checks, automated evidence, and manual review limits.
• row-level-security.md — How postgres RLS is used to enforce tenant isolation, when to use RlsContext, and the traps to avoid.
• rls-dev-setup.md — One-time setup so your local dev DB enforces RLS the way staging and prod do. Two paths: migrate-in-place or recreate. Read this if you've never run with a non-superuser dev role.
• typesense-search-sync.md — How public search is backed by Typesense and how the index is kept in sync with Postgres via direct Sidekiq jobs. Read before touching anything that indexes to Typesense, adds a searchable model/field, or changes the search read path.
• structure-sql-on-pg18.md — db/structure.sql is canonical and CI runs PostgreSQL 15. If your workstation runs 18, pg_dump rewrites unrelated DDL and buries your migration in churn. The regeneration procedure, the verification steps, and the substring-filter trap that has leaked onto an unrelated table twice. Read before committing a structure.sql change.
• authorization-pundit.md — The Pundit policy layer (who-can-do-what), how it differs from RLS (tenant isolation), the BasePolicy helpers, the required superadmin short-circuit, and the no-op-authorize-stub anti-pattern. Read before adding a controller action that mutates tenant-scoped data or writing a *Policy.

Current FeaturesCopy Anchor Link

See subdirectories for feature-specific documentation.