cosmosdb-project-structure

Azure Cosmos DB Project Structure

Standard Layout

database/
├── containers/
│   ├── orders.json                   # Container definition (partition key, indexing policy, TTL)
│   ├── customers.json
│   └── leases.json                   # Change feed lease container
├── models/
│   ├── Order.cs                      # Document model with type discriminator
│   ├── OrderItem.cs
│   ├── Customer.cs
│   └── BaseDocument.cs               # Base class with id, type, schemaVersion, _etag
├── migrations/
│   ├── 001_AddStatusField.cs
│   ├── 002_AddCompositeIndex.cs
│   └── MigrationRunner.cs
├── stored-procedures/
│   ├── bulkCreateItems.js
│   └── updateOrderStatus.js
├── udfs/
│   └── calculateDiscount.js
├── triggers/
│   ├── pre/
│   │   └── validateOrder.js
│   └── post/
│       └── updateAggregates.js
├── seed/
│   ├── lookup/
│   │   └── orderStatuses.json
│   └── dev/
│       └── sampleOrders.json
├── tests/
│   ├── OrderRepository.Tests.cs
│   └── MigrationRunner.Tests.cs
├── infrastructure/
│   ├── cosmos-account.bicep           # Or Terraform
│   └── indexing-policies/
│       ├── orders-policy.json
│       └── customers-policy.json
└── docs/
    └── partition-key-decisions.md     # Document partition key rationale

Rules

• One file per container definition in containers/
• Container definitions include: partition key, indexing policy, TTL, throughput, unique keys
• Models include type discriminator and schemaVersion for safe migrations
• migrations/ for versioned data migrations (not schema — Cosmos DB is schemaless)
• stored-procedures/, udfs/, triggers/ for server-side code (JavaScript)
• infrastructure/ for IaC definitions (Bicep or Terraform)
• docs/partition-key-decisions.md — REQUIRED: document why each partition key was chosen
• seed/lookup/ for reference data
• seed/dev/ for development-only sample data
• Base document class with common properties: id, type, schemaVersion, createdAt, _etag