Skip to main content

Phase 09B: Documentation

Objective: Create comprehensive documentation covering fundamentals, migration guides, i18n, multi-tenancy usage, and API references.

[!IMPORTANT] Revisit with Real Code: The docs/notes/fundamentals.md and docs/notes/migration-from-frappe.md currently show planned API designs. Before completing this phase, all examples must be validated with real, working code—actual Container initialization, DI wiring with dependency-injector, entrypoint overrides, and tested implementations.

1. Documentation (Basic Setup)​

[!NOTE] For comprehensive LLM-ready documentation, auto-generated API reference, screenshot automation, and machine-readable exports, see Phase 12: LLM-Ready Documentation.

1.1 Basic User Documentation ✅​

  • Create docs/user/ directory
  • Write essential guides:
    • Getting started (docs/user/getting-started.md)
    • Creating DocTypes (docs/user/creating-doctypes.md)
    • Using the Desk (docs/user/using-the-desk.md)
  • Auto-generated docs (scripts/generate_docs.py):
    • docs/user/_generated/field-types.md
    • docs/user/_generated/api-endpoints.md
  • Truthfulness tests (tests/docs/test_user_docs.py - 17 tests passing)

1.2 Basic Developer Documentation ✅​

  • Create docs/developer/ directory
  • Write essential guides:
    • Architecture overview (docs/developer/architecture.md)
    • Creating custom apps (docs/developer/creating-apps.md)
    • Defining DocTypes (docs/developer/defining-doctypes.md)
  • Auto-generated docs (scripts/generate_docs.py):
    • docs/developer/_generated/protocols.md (20 protocols)
    • docs/developer/_generated/hooks.md (10 hooks)
    • docs/developer/_generated/cli-reference.md
  • Truthfulness tests (tests/docs/test_developer_docs.py - 16 tests passing)

1.3 Framework Fundamentals ✅​

Already exists at docs/notes/fundamentals.md

  • Minimal core principle (irreplaceable: async Python, DI, protocols, entrypoints)
  • DI as universal composer
  • Bootstrap flow
  • Layer composition
  • Adding custom adapters
  • Testing with DI

1.4 Migration Guide (Frappe → Framework M) ✅​

Already exists at docs/notes/migration-from-frappe.md

  • Cover backend patterns
  • Cover frontend patterns
  • Practical examples

1.5 API Documentation ✅​

Already configured in adapters/web/app.py

  • Litestar auto-generates OpenAPI spec (/schema)
  • Swagger UI (/schema/swagger)
  • ReDoc (/schema/redoc)
  • Truthfulness tests (test_developer_docs.py::TestAPIDocumentation - 3 tests)

1.6 Example Apps ✅​

  • Create minimal example apps:
    • Simple TODO app (docs/examples/todo/)
    • Basic CRM (docs/examples/crm/)
  • Example index (docs/examples/README.md)

2. Internationalization (i18n)​

[!NOTE] This section includes both backend implementation (I18nProtocol, adapters) and frontend integration. Implementation happens in this phase alongside documentation.

2.1 Backend i18n ✅​

Already implemented - see docs/developer/i18n.md

  • Create I18nProtocol interface (core/interfaces/i18n.py):

    • translate(text, locale, context, default) -> str
    • get_locale() -> str
    • set_locale(locale) -> None
    • get_available_locales() -> list[str]

  • Create InMemoryI18nAdapter (adapters/i18n/__init__.py):

    • Dict-based translation storage
    • Add translations dynamically
    • String interpolation with context

  • Create Translation DocType:

    • source_text: str (original)
    • translated_text: str
    • locale: str (e.g. "hi", "ta", "en")
    • context: str | None (e.g. "button", "label")
    • Unique constraint: (source_text, locale, context)

  • Create DefaultI18nAdapter:

    • Load translations from DB on startup
    • Cache in memory (Redis optional)
    • Fallback chain: request locale → default locale → source text

  • Locale resolution order:

    • 1. Accept-Language header
    • 2. User preference (user.locale)
    • 3. Tenant default (tenant.attributes.default_locale)
    • 4. System default (settings.DEFAULT_LOCALE)

  • DocType field labels:

    • Field.label supports i18n key
    • Meta API returns translated labels based on request locale

2.2 Frontend i18n​

  • Install react-i18next:

    • Configure with backend translations endpoint
    • Lazy load locale bundles

  • Translation workflow:

    • Extract strings from components (i18next-parser)
    • Upload to Translation DocType
    • Download merged translations as JSON

  • Components:

    • useTranslation() hook in all components
    • <Trans> for interpolated strings
    • Locale switcher in navbar

2.3 Per-Tenant Locales​

  • Tenant can override default locale
  • Tenant can provide custom translations (override system)
  • Tenant locale from TenantContext.default_locale

3. Multi-Tenancy Usage & Documentation​

[!NOTE] TenantProtocol and adapters are implemented in Phase 06. This section covers usage documentation and frontend integration.

3.1 Tenancy Modes Documentation ✅​

  • Document Mode A (Single Tenant / Indie):

    • ImplicitTenantAdapter usage
    • Default tenant ID configuration
    • When to use (standalone deployments)

  • Document Mode B (Multi-Tenant / Enterprise):

    • HeaderTenantAdapter usage
    • Gateway configuration (X-Tenant-ID, X-Tenant-Attributes)
    • Citadel IAM integration for tenant extraction

  • Document tenant isolation patterns:

    • Logical isolation (tenant_id column, RLS)
    • Database-per-tenant (db_binds per tenant)
    • Schema-per-tenant (PostgreSQL schemas)

3.2 Using TenantContext in Code ✅​

Documented in docs/developer/tenancy-modes.md - "Using TenantContext in Code" section

  • Document injection pattern:

    • Dependency injection via request.state.tenant
    • Feature flags from tenant attributes
    • Example endpoints using TenantContext

  • Document tenant-aware queries:

    • Automatic RLS filtering with GenericRepository
    • Manual tenant_id filtering with FilterSpec
    • Cross-tenant queries (admin only)

3.3 Frontend Multi-Tenancy ✅​

Documented in docs/developer/tenancy-modes.md - "Frontend Multi-Tenancy" section

  • Tenant context in frontend:

    • Extract from JWT or API response
    • Store in React context (TenantProvider, useTenant hook)
    • Pass tenant_id in API requests (if not in headers)

  • Tenant-specific UI:

    • Tenant branding (logo, colors) - useTenantBranding hook
    • Feature flags from tenant.attributes - FeatureGate component
    • Tenant selector (admin UI) - TenantSelector component

3.4 Switching Adapters ✅​

Documented in docs/developer/tenancy-modes.md - "Switching Adapters" section

  • Document adapter selection:
    • Configuration via framework_config.toml (mode = "single" | "multi")
    • Factory function create_tenant_adapter_from_headers()
    • Entrypoint registration for custom adapters
    • Testing with MockTenantAdapter

4. Theming ✅​

Implemented in frontend - see docs/developer/theming.md

  • Add theme support:
    • Light/dark mode with ThemeContext and useTheme hook
    • Custom color schemes via CSS variables (:root and .dark)
    • Store user preference in localStorage with system detection fallback
    • ThemeToggle component integrated in Navbar

5. Testing​

5.1 Frontend Tests ✅​

Complete testing infrastructure - see docs/developer/frontend-testing.md

  • Unit tests for components:

    • Test AutoForm rendering (12 tests)
    • Test AutoTable rendering (11 tests)
    • Test ThemeToggle functionality (6 tests)
    • Test form validation

  • Integration tests:

    • Test full CRUD flow (3 tests)
    • Test theme persistence (7 tests)
    • Test navigation
    • Test real-time updates

  • E2E tests with Playwright:

    • Test user login workflows (7 tests)
    • Test create record workflows (9 tests)
    • Test cross-browser compatibility (10 tests)

  • Test infrastructure:

    • Vitest setup with happy-dom
    • Testing Library integration
    • Playwright configuration
    • CI/CD test scripts
    • Coverage reporting

Validation Checklist​

Before moving to Phase 10, verify:

  • Frontend can render any DocType
  • Forms are generated from metadata
  • Tables support sorting and filtering
  • Real-time updates work
  • Documentation is comprehensive
  • Example apps demonstrate features

Anti-Patterns to Avoid​

❌ Don't: Hardcode DocType-specific UI ✅ Do: Generate UI from metadata

❌ Don't: Build separate forms for each DocType ✅ Do: Use generic AutoForm component

❌ Don't: Skip documentation ✅ Do: Document as you build

❌ Don't: Ignore accessibility ✅ Do: Follow WCAG guidelines