Skip to content

Plugin Development

This section covers extending Atlas through its public Python and TypeScript contracts. A plugin is a trusted, operator-selected backend package, frontend package, or pair of packages whose contributions are composed into a distribution at build time.

Who this section is for

Use this section if you build or maintain an Atlas plugin. It explains:

  • which extension mechanism fits the behavior or data you want to add;
  • how Entity Kinds, Facets, frontend Contributions, Capabilities, and Extension Points differ;
  • how plugin code is selected and validated as part of a distribution; and
  • which boundaries keep Core and sibling plugins isolated.

Start here

If the terms above are new, read the Domain glossary first. Then use Choose an extension mechanism to select the contract that matches your change before following Build your first plugin.

  1. Domain glossary teaches the shared extension vocabulary.
  2. Choose an extension mechanism maps your data, UI, runtime collaboration, authorization, or background-work need to the supported contract.
  3. Build your first plugin follows a complete plugin path.
  4. Choose a plugin layout helps select a backend-only, frontend-only, or full-stack package shape and its responsibilities.
  5. Frontend contributions explains how to add routes, navigation, detail tabs, and home widgets that compose safely.
  6. Entity kinds and facets covers owned catalog kinds and data attached to an existing kind.
  7. Backend collaboration covers publishing and consuming backend contracts without crossing plugin boundaries.
  8. Authentication provider SDK covers credential and redirect verification through atlas.auth.providers.v1.
  9. Plugin contract reference lists the exact Python and TypeScript package surface.
  10. Plugin permissions, models, migrations, and jobs, testing, and debugging cover how to make, validate, and diagnose a safe extension.
  11. Compatibility and lifecycle explains how to prepare a compatible upgrade or removal.
  12. Standard Catalog and the other built-in feature notes show first-party implementations that use the same contracts.

Section boundary

A plugin cannot import another plugin's models or internal modules, replace another plugin's contributions, patch Core behavior, or install itself from a running Atlas instance. Distribution selection and lifecycle procedures belong in Operating Atlas; installed product behavior belongs in Features and Integrations.