Skip to content

doc

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

doc

README.md

w# Project Documentation

This folder hosts the project documentation. Files here are Markdown (.md) unless otherwise noted.

📚 Quick Navigation

Core Reference (Start Here)

🚀 Getting Started

New to the project?

  1. Read planning/product-vision.md - High-level vision and goals
  2. Read planning/v1-plan.md - Current implementation status and V1 scope
  3. Follow setup/dev-setup.md - Set up your local environment
  4. Review setup/contributing.md - Contribution guidelines

📂 Documentation Structure

/help - User Documentation (Published)

Published to: doc.kanap.net

End-user documentation built with MkDocs. This folder is deployed automatically and should not contain any internal/technical content.

  • docs/en/: English documentation (source files)
  • docs/fr/: French documentation (future)
  • mkdocs.yml: MkDocs configuration
  • _process/: Documentation generation templates and inventory (not published)

To build locally:

cd doc/help
pip install mkdocs-material
mkdocs serve  # Preview at http://localhost:8000

To generate/update a page: Use /doc-page <route> for a single page, /doc-batch <category> for bulk generation, or /doc-check for staleness detection. Commands are defined in .claude/commands/doc-*.md; there is also a Codex skill at .codex/skills/user-manual-maintainer/.

/on-premise - On-Premise Deployment (Internal)

User-facing on-premise guides are in /help/docs/en/on-premise/ (published to doc.kanap.net).

/setup - Development Environment

/operations - Deployment & Operations

/features - Feature Implementation Guides

Patterns (features/patterns/)

  • workspace-patterns.md: ⭐ Comprehensive workspace implementation guide (RLS, tenant deletion, lifecycle, editor patterns)
  • backend-patterns.md: ⭐ Backend patterns & abstractions (BaseDeleteService, TenancyManager, service decomposition, DTOs)
  • csv-import-export.md: CSV workflows, validation, templates

Workspaces (features/workspaces/)

Components (features/components/)

Master Data (features/master-data/)

/database - Database Documentation

  • database-indexes.md: Performance indexes, monitoring, troubleshooting (consolidated guide with quick start)

/planning - Product Planning & Vision

  • product-vision.md: Purpose, personas, outcomes, guiding principles
  • v1-plan.md: V1 scope, timeline, implementation status, acceptance criteria (consolidated V1 spec + implementation plan)
  • requirements.md: Functional requirements and constraints
  • roadmap.md: Near-term milestones and backlog themes
  • evaluation.md: Quality criteria and metrics
  • security.md: Threat model, controls, authentication/authorization

/adr - Architecture Decision Records

/templates - Development Templates

/samples - CSV Templates

Sample CSV files for import/export:

  • accounts.csv, companies.csv, departments.csv, suppliers.csv, users.csv
  • spend_items.csv, spend_versions.csv, spend_amounts_*.csv, spend_allocations.csv
  • capex.csv, opex.csv, contracts.csv

/archive - Historical Documentation

  • archive/fixes/: Historical fix documentation (connection pool fix, RBAC multi-role fix, etc.)
  • archive/implementation-steps/: Completed implementation step guides (01-20)
  • archive/planning/completed-2025/: Completed implementation plans from 2025 (Entra SSO, IT Ops, Interfaces, Applications Portfolio, CoA, Locations, Files/S3, RBAC, Cloudflare, Marketing, Application Versions)

/user-manual - (Deprecated)

Legacy location for user documentation. Content has been migrated to /help/docs/en/. This folder will be removed in a future cleanup.

🎯 Key Concepts

Multi-Tenancy & Deployment Modes

  • Single-DB approach: Shared PostgreSQL with Row-Level Security (RLS)
  • Tenant isolation: tenant_id on all tables, RLS policies enforce per-request context
  • Per-request binding: TenantInitGuard sets app.current_tenant from subdomain
  • Platform admin: Separate host for tenant management (PLATFORM_ADMIN_HOST)
  • On-premise (single-tenant): DEPLOYMENT_MODE=single-tenant bypasses subdomain routing, disables billing/platform-admin, auto-provisions tenant on first boot

See: architecture.md (Multitenancy section), on-premise/technical-design.md (on-prem design), features/patterns/workspace-patterns.md (RLS requirements)

Workspace Pattern

  • Route-driven editing: /module/items/:id/:tab (not modals)
  • Explicit Save/Reset: Dirty guards prevent data loss
  • Prev/Next navigation: Preserves list context (sort, filters, search)
  • Deep linking: Grid cells open specific tabs/years

See: features/patterns/workspace-patterns.md ⭐

Lifecycle Management

  • disabled_at as source of truth: Past date = disabled, NULL/future = enabled
  • Derived status: Backend computes status enum from disabled_at
  • Historical queries: Period-aware filtering includes items active during timeframe
  • Frontend: StatusLifecycleField component handles toggle + date picker

See: features/patterns/workspace-patterns.md (Lifecycle Management section)

Allocation Methods

Six allocation methods for cost distribution:

  • Auto: default, headcount, it_users, turnover (computed from metrics)
  • Manual: manual_company, manual_department (explicit percentages, auto-recalculated)

See: adr/0001-allocation-model-and-metrics.md

Backend Patterns

Shared abstractions for consistency and maintainability:

  • BaseDeleteService: Consolidated delete logic with cascade relations, storage cleanup, audit logging
  • TenancyManager: Request-scoped tenant context and transaction management
  • Service Decomposition: Large services split into focused sub-services using facade pattern
  • Type Safety: Zod DTOs, typed decorators (@Tenant()), response types

See: features/patterns/backend-patterns.md ⭐

Frontend Patterns

Shared hooks and components for consistency:

  • useModuleNavigation: Generic navigation hook replacing module-specific hooks
  • useVirtualRows: Virtual scrolling for large lists
  • WorkspaceLayout: Reusable workspace page layout with tabs
  • EnumEditor: Generic settings editor with virtual scrolling

See: frontend-architecture.md

🔧 Common Tasks

Implementing a New Workspace

  1. Read features/patterns/workspace-patterns.md ⭐
  2. Add tenant_id + RLS policies to tables
  3. Update tenant deletion script (admin-tenants.service.ts)
  4. Implement shell + editors following patterns
  5. Run RLS self-test (npm run test:rls)
  6. Run CSV smoke test if applicable

Adding a New Table

  1. Add tenant_id uuid NOT NULL column
  2. Create RLS policies (USING + WITH CHECK)
  3. Add composite indexes (tenant_id leading)
  4. Update tenant deletion purge order
  5. Use request-scoped EntityManager in services
  6. Run RLS self-test

Debugging Performance Issues

  1. Check database/database-indexes.md for index guidance
  2. See operations/connection-pool-troubleshooting-guide.md
  3. Check operations/runbook.md for monitoring procedures

📖 Documentation Standards

  • Template: Use template.md for new documents
  • Metadata: Include Purpose, Audience, Status (draft/current/archived/deprecated), Owner, Last Updated
  • Related Documentation: Add links to related docs at the top of each document
  • Cross-References: Use **See:** [doc-name.md](path/to/doc.md) instead of duplicating content
  • Conciseness: Keep docs focused; link to authoritative sources for details
  • Diagrams: Prefer diagrams-as-code (Mermaid) embedded in Markdown
  • Code references: Use file_path:line_number pattern for linking to code

Documentation Governance

  • Quarterly Review: Review /planning/ directory each quarter for completed implementation plans to archive
  • Archive Location: Completed plans go to /archive/planning/completed-YYYY/
  • Status Updates: Mark implementation plans as "Status: IMPLEMENTED (YYYY-MM-DD)" when complete
  • Avoid Duplication: Maintain single source of truth; use cross-references instead of copying content
  • Link Maintenance: When moving files, update all cross-references in README.md and related docs

🏷️ Current Status (Summary)

Implemented Features

✅ Multi-tenancy (RLS, tenant provisioning, subdomain routing) ✅ OPEX & CAPEX modules (workspaces, budgets, allocations, tasks) ✅ Contracts (CRUD, OPEX linking, attachments, tasks) ✅ Master data (companies, departments, suppliers, accounts, analytics, contacts) ✅ Reporting (Top 10, Delta, Budget Trend (OPEX/CAPEX), Budget Column Comparison, Consolidation, Chargeback) ✅ RBAC (roles, permissions, seat licensing) ✅ Budget Operations (freeze, copy columns, copy allocations, reset) ✅ Platform Admin (tenant management, freeze/delete, plan updates) ✅ CSV import/export (all entities) ✅ Lifecycle management (disabled_at source of truth) ✅ Connection pool optimization ✅ Database indexes (90-95% performance improvement) ✅ Email notifications (event-driven + scheduled weekly review digest) ✅ User settings (profile editing, notification preferences) ✅ Rate limiting (app-level throttling on auth and public endpoints) ✅ On-premise deployment (single-tenant mode, feature flags, first-boot provisioning, CI matrix)

In Progress

None - V1+ features complete

Planned

See planning/roadmap.md

🔗 External Links

  • Repository: (Add your Git repo URL)
  • Issue Tracker: (Add your issue tracker URL)
  • CI/CD: (Add your CI/CD dashboard URL)
  • QA Environment: qa.kanap.net
  • Production: kanap.net

📞 Support & Questions

📝 Document Conventions

  • Relative links: Use relative paths for internal docs (e.g., [file](setup/dev-setup.md))
  • Code blocks: Use appropriate language tags for syntax highlighting
  • Callouts: Use emoji prefixes for emphasis (⚠️ Warning, ✅ Complete, ⭐ Important)
  • Sections: Use --- for horizontal separators between major sections
  • Tables: Use tables for structured data (checklists, comparisons, status)

Last Updated: 2026-02-15 Document Owner: Engineering Team