Extending Atlas
Atlas is designed to be evolved, not just operated. Most extension is declarative — adding a data provider, an ontology field, or a risk matrix is mostly authoring YAML and a thin adapter, not rewriting the core. This section is the engineer's field guide to the system's extension points.
The extension points at a glance
| I want to… | Difficulty | Mostly touches | Guide |
|---|---|---|---|
| Add a data provider | Low–Medium | plugins/<slug>/, register provider | Add a provider |
| Add an OSINT module (crew) | Medium | plugins/osint/, registry | Add an OSINT module |
| Add an ontology entity type / field | Medium | ontology_v3.5.yaml, matchers | Add an entity type |
| Add / change a risk matrix | Low | matrix YAML, reference data | Add a risk matrix |
| Add a reference dataset | Low | reference-data registry | Add a risk matrix |
| Add a graph relationship/query | Low–Medium | ontology_v3.5.yaml, Cypher | Add an entity type |
| Add a frontend page / hook / store | Low–Medium | frontend/src/ | Add a frontend feature |
| Add a backend router/endpoint | Low | src/api/, tenant session | Add a frontend feature |
Two rules that keep extensions safe
- Fail loud at boot. The TranslationRegistry and SchemaCache validate plugins, mappings, and the ontology at startup. A mis-authored extension stops the boot rather than corrupting data — so you find out immediately, with all problems aggregated into one error, not one at a time.
- Tenant-scope everything. Any new data path must run through the tenant context and Row-Level Security. A query without a tenant context returns nothing (fail-closed); never bypass it.
Before you start
- Read the subsystem's architecture page first (each guide links to it).
- Extensions are validated against the active ontology version; if your change requires a new ontology version, see Add an entity type.
- Run the test suites — plugin and mapping changes are covered by CI gates that validate against the ontology.
Pick a guide from the table above to continue.