> 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/database-selection.md).

# Database Selection

## AIC Standard

MongoDB is AIC's primary persistence layer.

This is the default for new AIC-owned products, platforms and accelerators unless a project-specific architecture decision approves another store.

The database decision must be based on domain shape, operational needs, security requirements, customer constraints and supportability. It must not be based on personal preference.

## Default Decision Matrix

| Scenario                                | Default decision                                        | Reason                                                              |
| --------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
| SaaS product data                       | MongoDB                                                 | Flexible aggregate model, tenant-aware collections, fast iteration. |
| Operational records                     | MongoDB                                                 | Documents map well to evolving operational state.                   |
| Intelligence, detection or message data | MongoDB                                                 | Handles varied, metadata-rich records.                              |
| Audit events                            | MongoDB append-only collection or dedicated audit store | Durable event record with flexible schema.                          |
| Workflow state                          | MongoDB                                                 | Durable state with document-level updates.                          |
| Cache or temporary lookup               | Redis                                                   | Fast, short-lived and disposable.                                   |
| Strong relational domain                | Relational database with EF Core                        | Better for strict relational constraints.                           |
| Customer-mandated SQL                   | EF Core or Dapper                                       | Customer architecture constraint.                                   |
| Reporting and analytics                 | Separate analytical model                               | Do not overload the operational store.                              |
| Search-heavy requirements               | MongoDB Atlas Search or dedicated search engine         | Better query capability and performance.                            |

## MongoDB Selection Criteria

Choose MongoDB when:

* the domain is aggregate-oriented
* the schema is expected to evolve
* records contain rich metadata
* data is naturally document-shaped
* high ingest speed is required
* tenant-specific data shapes may vary
* the system benefits from flexible indexing
* the team needs rapid iteration without weak governance

## Relational Selection Criteria

Choose a relational database when:

* the domain requires strong relational constraints
* complex joins are central to the application
* SQL reporting is a primary requirement
* customer policy mandates relational persistence
* existing systems already expose relational integration points
* cross-record transactional consistency is non-negotiable

## Redis Selection Criteria

Choose Redis when:

* data is temporary
* the source of truth exists elsewhere
* low-latency lookup is required
* expiry is part of the design
* loss of cached data is acceptable
* the data can be rebuilt

Redis is not a primary persistence layer.

## Required Architecture Decision

Every project must record:

* selected primary store
* reason for selection
* alternatives considered
* data ownership model
* tenant isolation model
* backup and recovery approach
* indexing approach
* migration or schema evolution approach
* test database approach
* operational support model

## Quality Gate

Before implementation starts:

* database choice approved
* collection or schema strategy documented
* tenant isolation reviewed
* indexing approach drafted
* local development approach confirmed
* integration test approach confirmed
* backup and restore assumptions defined
* security requirements confirmed