Multi-Tenancy Documentation Index

Project: MyClinicsoftSoft
Last updated: 2026-04-23

Documentation Overview

The multi-tenancy implementation for MyClinicsoftSoft is documented across four comprehensive guides:

📘 MULTI_TENANCY.md — Complete Reference

Purpose: Comprehensive architectural and technical reference
Audience: Architects, senior developers, system designers
Content:

Complete architecture overview
Tenant model & schema details
Subdomain resolution logic
Session & cookie strategy
Data isolation patterns
Tenant onboarding & subscription
All CLI scripts
Environment variables
Known issues & gaps
Key file reference

Start here if: You need to understand the entire system or make architectural decisions

⚡ MULTI_TENANCY_QUICK_START.md — Developer Guide

Purpose: Practical quick-start guide for developers
Audience: Developers adding features or fixing bugs
Content:

Common task patterns (get tenant, query, create)
Local development setup
Creating/deleting tenants
Common patterns (guarded routes, patient queries)
Testing scenarios
Adding tenant support to new models
Debugging multi-tenant issues
Performance notes
Security checklist
Environment variables checklist

Start here if: You're new to the project or need to implement a multi-tenant feature

🔒 TENANT_ISOLATION_SECURITY.md — Security Deep Dive

Purpose: Understand isolation guarantees, threats, and security model
Audience: Security team, architects, code reviewers
Content:

Isolation guarantees (4 layers)
Threat model (7 scenarios)
Data access control patterns
Cross-tenant exposure risks
Authentication & session isolation
Authorization & permissions
Resource limits & quotas
Audit logging
Security checklist (40+ items)
Incident response procedures

Start here if: You're doing security review, threat modeling, or investigating a data breach

💻 MULTI_TENANCY_CODE_PATTERNS.md — Code Examples

Purpose: Practical code patterns and examples
Audience: Developers implementing features
Content:

4 API route patterns (GET, POST, PATCH, DELETE)
6 database query patterns
3 server component patterns
2 error handling patterns
2 testing patterns
2 migration patterns
3 performance patterns

Start here if: You need copy-paste code examples for your implementation

Quick Navigation by Task

I'm a new developer, what do I read?

Start: MULTI_TENANCY_QUICK_START.md (10 min read)
Setup: Follow "Development Workflow" section
Deep dive: MULTI_TENANCY.md sections 1-5 (20 min)
Coding: MULTI_TENANCY_CODE_PATTERNS.md

I need to add a new model/feature with tenant support

Quick reference: MULTI_TENANCY_QUICK_START.md → "Adding Tenant Support to New Models"
Code examples: MULTI_TENANCY_CODE_PATTERNS.md → Pattern 1.2 (POST) + Pattern 2.1
Security: TENANT_ISOLATION_SECURITY.md → Section 9 (Security Checklist)

I found a data isolation bug, what do I do?

Identify: TENANT_ISOLATION_SECURITY.md → Section 4 (Cross-Tenant Data Exposure Risks)
Fix: MULTI_TENANCY_CODE_PATTERNS.md → Sections 1-2
Verify: MULTI_TENANCY_QUICK_START.md → "Debugging Multi-Tenant Issues"
Test: MULTI_TENANCY_CODE_PATTERNS.md → Section 5.1 (Test Tenant Isolation)

I'm doing a security review

Read: TENANT_ISOLATION_SECURITY.md (entire, 30 min)
Check: Section 9 → Security Checklist
Verify: Section 4 → Cross-Tenant Data Exposure Risks
Reference: MULTI_TENANCY.md → Section 14 (Known Issues & Gaps)

I need to debug a tenant-related issue

Symptoms: MULTI_TENANCY_QUICK_START.md → "Debugging Multi-Tenant Issues"
Understanding: MULTI_TENANCY.md → Section 3 (Subdomain Resolution)
Patterns: MULTI_TENANCY_CODE_PATTERNS.md → Database Query Patterns
Security: TENANT_ISOLATION_SECURITY.md → Section 2 (Threat Model)

I'm setting up a new environment (staging, production)

Reference: MULTI_TENANCY.md → Section 13 (Environment Variables)
Checklist: TENANT_ISOLATION_SECURITY.md → Section 9 (Configuration Checklist)
Quick start: MULTI_TENANCY_QUICK_START.md → "Setup"

Section Cross-Reference

Key Files in the Codebase

Core Tenant Utilities

File	Purpose	Read For
`lib/tenant.ts`	Subdomain extraction, tenant resolution	How tenants are identified
`lib/tenant-query.ts`	Query helpers (mostly unused)	Tenant filter utilities
`app/lib/dal.ts`	Session creation & verification	JWT structure, tenantId embedding
`models/Tenant.ts`	Tenant schema	Model structure

API Routes

File	Purpose	Read For
`app/api/tenants/onboard/route.ts`	Tenant creation	Onboarding flow
`app/api/tenants/public/route.ts`	Tenant lookup	Public tenant API
`app/api/subscription/`	Billing & subscription	Payment handling
`app/api/audit-logs/route.ts`	Audit log queries	Tenant-scoped logging

Configuration & Middleware

File	Purpose	Read For
`proxy.ts`	Edge middleware (CSRF, cron auth)	Security features
`.env.example`	Environment variable template	Configuration

Scripts

File	Purpose	Run With
`scripts/onboard-tenant.ts`	Interactive tenant creation	`npm run tenant:onboard`
`scripts/delete-tenant.ts`	Tenant deletion	`npm run tenant:delete`
`scripts/seed-data.ts`	Demo data generation	`npm run seed`

Common Questions & Answers

Q: How does a request know which tenant it belongs to?

A: Through subdomain extraction. The Host header is parsed to extract the subdomain (e.g., "clinic-a" from "clinic-a.myclinicsoft.com"), then looked up in the Tenant collection.

Read: MULTI_TENANCY.md → Section 3
Code: lib/tenant.ts → extractSubdomain(), getTenantContext()

Q: Can a patient belong to multiple clinics?

A: Yes. The Patient model uses tenantIds (array) instead of tenantId (single). This allows patients to be shared across clinics they've visited.

Read: MULTI_TENANCY.md → Section 5
Pattern: MULTI_TENANCY_CODE_PATTERNS.md → Pattern 2.2

Q: What happens if I forget to filter by tenantId?

A: Data from all clinics is returned. This is a critical security bug.

Read: TENANT_ISOLATION_SECURITY.md → Section 4.1
Debug: MULTI_TENANCY_QUICK_START.md → Debugging

Q: How are sessions scoped to tenants?

A: The JWT token contains a tenantId field. When a staff member logs in from a subdomain, their tenant is embedded in the token. All subsequent requests include the tenantId from the JWT.

Read: MULTI_TENANCY.md → Section 4
Deep dive: TENANT_ISOLATION_SECURITY.md → Section 5

Q: What's the difference between `COOKIE_DOMAIN` and `ROOT_DOMAIN`?

ROOT_DOMAIN (e.g., "myclinicsoft.com") — Extracted to identify subdomains
COOKIE_DOMAIN (e.g., ".myclinicsoft.com") — Allows cookies to be shared across subdomains

Read: MULTI_TENANCY.md → Section 13
Details: MULTI_TENANCY.md → Section 4

Q: How do I test tenant isolation?

A: Create test documents with different tenantIds, then verify that queries with one tenantId don't return documents from other tenants.

Read: MULTI_TENANCY_CODE_PATTERNS.md → Section 5.1
Manual test: MULTI_TENANCY_QUICK_START.md → Testing

Q: What are the known issues with multi-tenancy?

A: There are 8 documented issues (1 critical, 3 moderate, 4 minor):

proxy.ts not wired as middleware (CSRF protection inactive)
Some API routes use non-existent schema fields
addTenantFilter helpers unused

Read: MULTI_TENANCY.md → Section 14

Q: How do I add tenant support to a new model?

A: Add a tenantId field to the schema, filter all queries by it, and ensure the model is deleted in delete-tenant.ts.

Read: MULTI_TENANCY_QUICK_START.md → Adding Tenant Support

Document Maintenance

Last reviewed: 2026-04-23
Last updated: 2026-04-23
Maintainers: Clinic Management System Team
Review frequency: Quarterly (or after major features)

How to Update These Docs

Found an error or outdated info? Update the relevant doc file
New feature added? Add a pattern to MULTI_TENANCY_CODE_PATTERNS.md
New security consideration? Add to TENANT_ISOLATION_SECURITY.md
Fixed a known issue? Remove from MULTI_TENANCY.md Section 14

Additional Resources

External References

Related Docs in Project

README.md — Project overview
models/RELATIONSHIPS.md — Data model relationships
docs/SECURITY.md — General security (if exists)
docs/BILLING_AND_INVOICING.md — Subscription/billing context

Navigation aid for MyClinicsoftSoft multi-tenancy documentation