> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/data-and-persistence-standards/mongodb-standards.md).

# MongoDB Standards

## Purpose

This page defines AIC's standard for MongoDB design, implementation, testing and operation.

MongoDB is the default primary persistence layer for AIC systems. It must be used with discipline, not as a dumping ground for unstructured data.

## Design Principles

* Model around aggregates and access patterns.
* Keep tenant isolation explicit.
* Design indexes before high-volume use.
* Store only what the service owns or is authorised to retain.
* Prefer simple documents over over-normalised structures.
* Avoid unbounded arrays and uncontrolled document growth.
* Use explicit versioning where document shape may evolve.
* Keep audit data append-only where possible.
* Make correlation identifiers first-class fields.
* Use UTC for all persisted timestamps.

## Collection Naming

Collection names should be clear, plural and domain-aligned.

Examples:

```
organisations
users
cases
detections
auditEvents
apiKeys
subscriptions
```

Avoid names that expose implementation details or temporary project language.

## Document Identity

Use a consistent identity model.

AIC systems may use:

* MongoDB `ObjectId` where internal identity is sufficient
* GUID / UUID where identity must be generated outside MongoDB
* domain-specific strongly typed identifiers where the domain benefits

Public APIs should not leak persistence implementation unless deliberately approved.

## Tenant Isolation

Tenant-owned documents must include a tenant or organisation identifier.

Example:

```csharp
public sealed record CaseDocument
{
    public required string Id { get; init; }

    public required string OrganisationId { get; init; }

    public required string Reference { get; init; }

    public required string Status { get; init; }

    public required DateTime CreatedAtUtc { get; init; }

    public required DateTime UpdatedAtUtc { get; init; }
}
```

All tenant-scoped queries must include tenant filtering.

## Indexing Standard

Indexes must support real query patterns.

Common index patterns:

* `{ organisationId, id }`
* `{ organisationId, status, createdAtUtc }`
* `{ organisationId, updatedAtUtc }`
* `{ correlationId }`
* `{ externalReference }`

Index definitions should be created through controlled startup, migration tooling or infrastructure automation. They must be reviewed like code.

## Schema Evolution

MongoDB does not remove the need for schema governance.

Schema changes must consider:

* backward compatibility
* deserialization of old documents
* migration of existing documents
* API compatibility
* index changes
* rollback or fix-forward approach

Use a document version field where useful.

Example:

```csharp
public sealed record VersionedDocument
{
    public required string Id { get; init; }

    public required int SchemaVersion { get; init; }
}
```

## Concurrency

Use optimistic concurrency for records that may be updated by multiple processes.

Options include:

* version field
* updated timestamp with compare-and-set
* ETag-style value

Do not silently overwrite concurrent changes.

## Transactions

MongoDB transactions are permitted but should not be the default design escape hatch.

Use transactions when:

* multiple documents must change atomically
* compensating actions are not acceptable
* the business operation cannot tolerate partial completion

Prefer aggregate design that avoids cross-document transactions where possible.

## Security

MongoDB security controls must include:

* encrypted connection strings in secret management
* network restriction
* least privilege database users
* environment separation
* audit logging where required
* backup and restore configuration
* sensitive field review
* no production data in local development without approval

## Testing

MongoDB integration tests should use:

* disposable containers, or
* isolated test databases, or
* unique collection/database names per test run

Tests must clean up after themselves or use disposable infrastructure.

## Quality Gate

Before release:

* collections documented
* indexes reviewed
* tenant filtering reviewed
* backup and restore understood
* schema evolution approach recorded
* concurrency risks reviewed
* integration tests cover critical persistence paths
* monitoring agreed