Documentation Writing Guide

Standard rules and conventions for writing feature documentation in the Oktivo backend project. Use this as a reference when asking AI to write docs on a specific feature.

Purpose

Every major feature, system, or bugfix should have a dedicated .md file in the docs/ folder. These docs serve as the single source of truth for how a feature works end-to-end from the database schema to the API layer to the LiveKit integration to the UI.

Document Structure

Every feature doc MUST follow this structure in order:

1. Title & One-Line Summary

# Feature Name

One sentence explaining what this feature does and why it exists.

2. Architecture Overview (Mermaid Diagram)

Every doc MUST include at least one Mermaid diagram showing the high-level flow. Use sequenceDiagram for request/response flows, flowchart for decision logic, and erDiagram for data models.

## Architecture Overview

```mermaid
sequenceDiagram
    participant UI as Frontend
    participant API as Client Backend
    participant LK as LiveKit
    participant DB as MongoDB
    ...
`` `

3. How It Works (Step-by-Step)

Break the feature into numbered steps. Each step should include:

• What triggers it (UI action, API call, cron job, webhook)
• Which file handles it (controller → service → repository → model)
• What data flows (request body, DB writes, external API calls)
• What the expected outcome is

4. File-by-File Breakdown

A table listing every file involved, what it does, and why it exists:

## File Reference

| File | Role | Key Functions |
|------|------|---------------|
| `controllers/feature.controller.ts` | API layer validates input, calls service | `createX()`, `updateX()` |
| `services/feature.service.ts` | Business logic orchestrates operations | `doThing()` |
| `models/Feature.ts` | Mongoose schema + TypeScript interface | `IFeature`, `FeatureDocument` |
| `repositories/feature.repository.ts` | DB queries CRUD operations | `create()`, `findByUID()` |

5. Data Model (Schema)

Show the MongoDB schema with field types, defaults, and indexes. Use a Mermaid erDiagram or a code block.

6. API Endpoints

List all relevant endpoints with method, path, auth, request body, and response:

## API Endpoints

### Create X
- **Method**: `POST`
- **Path**: `/api/feature/resource`
- **Auth**: `verifyJwt` → `requireRole("superadmin")`
- **Body**:
  ```json
  {
    "name": "string",
    "config": { ... }
  }

• Response: 201 with created resource

### 7. External Integrations

If the feature talks to LiveKit, S3, a SIP provider, or any external service document:
- What data is sent
- What data is received
- What happens on failure (retry? rollback? log and continue?)

### 8. How to Test (End-to-End)

Step-by-step instructions to test the feature from the UI (or API) through to the backend. Include:
- Prerequisites (env vars, seed data, running services)
- Exact UI steps or curl/API commands
- What to verify in the database
- What to verify on LiveKit (if applicable)
- What to verify in logs

### 9. Troubleshooting

A table of common symptoms, causes, and fixes:

```markdown
## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Error message X | Missing config Y | Set Y in .env |

10. Changelog (Optional)

If the doc covers a bugfix or incremental change, include a brief changelog at the bottom.

Writing Rules

Be Specific, Not Generic

• Reference actual file names, function names, and field names
• Include actual JSON payloads, not abstract descriptions
• Show real examples with realistic data (use placeholder values like org_ABC123, +919876543210)

Show the Data Flow

• For every operation, trace the data from request → controller → service → repository → model → external API
• Show what fields are read, what fields are written, and what fields are passed to external services

Include Mermaid Diagrams

• Use sequenceDiagram for multi-step flows involving multiple services
• Use flowchart TD for decision trees and branching logic
• Use erDiagram for data model relationships
• Keep diagrams focused one diagram per concept, not one giant diagram for everything

Document the "Why"

• Don't just say "this function exists" explain WHY it exists
• If there's a cleanup step, explain what goes wrong without it
• If there's a fallback, explain what scenario triggers it

Document Edge Cases

• What happens when the external service is down?
• What happens when data is missing or stale?
• What happens in a multi-developer environment?

Keep It Updated

• When you change a feature, update the doc in the same PR
• If a doc is outdated, note it at the top: > ⚠️ This doc may be outdated. Last verified: YYYY-MM-DD

File Naming Convention

• Use UPPER-KEBAB-CASE.md for feature docs (e.g., SIP-TRUNK-SYSTEM.md, CREDIT-MANAGEMENT-SYSTEM.md)
• Use lowercase for utility docs (e.g., shared-package.md)
• Place all docs in OP_oktivo_backend/docs/

Template

When asking AI to write a doc, provide this prompt structure:

Write a doc for [FEATURE NAME] following the rules in docs/index.md.

Key files:
- [list the main files involved]

The doc should cover:
1. Architecture overview with mermaid diagram
2. Step-by-step how it works
3. File-by-file breakdown
4. Data model / schema
5. API endpoints
6. External integrations (LiveKit, etc.)
7. How to test end-to-end from UI
8. Troubleshooting table

Inportant: Doc should not too long it should be to the point and easy to understand and readable. If any techinal termilogy is there then add a basic defination of that termilogy or add a external link to read abount it.