architecture-overview

name	architecture-overview
description	Use when exploring the aiida-core codebase structure, looking for key files, or understanding how packages relate to each other.

AiiDA Core Architecture

Source layout

The source code lives under src/aiida/ with these main packages:

Package	Purpose
brokers/	Message broker interface (RabbitMQ via kiwipy)
calculations/	Built-in calculations
cmdline/	CLI (verdi command) built with click
common/	Shared utilities, exceptions, warnings, constants
engine/	Workflow engine: process runner, daemon, persistence, transport tasks (with plumpy dependency)
manage/	Configuration management, manager singleton
orm/	Object-relational mapping: nodes, groups, users, computers, querybuilder
parsers/	Built-in parser plugins
plugins/	Plugin entry point system and factories
repository/	File repository abstraction layer
restapi/	Flask-based REST API (soon to be replaced by aiida-restapi)
schedulers/	Built-in HPC scheduler plugins (SLURM, PBS, SGE, LSF, etc.)
storage/	Storage backends (primarily psql_dos (sqlite_dos) for PostgreSQL (SQLite) + disk-objectstore)
tools/	Utility tools (graph visualization, archive operations, data dumping, etc.)
transports/	Built-in Transport plugins (SSH, local)
workflows/	Built-in workflows

Key entry points

Area	Key file(s)	Purpose
Engine core	src/aiida/engine/processes/process.py	Base Process class
CalcJob	src/aiida/engine/processes/calcjobs/calcjob.py	CalcJob implementation
CalcJob file ops	src/aiida/engine/daemon/execmanager.py	File copying, job submission, retrieval
WorkChain	src/aiida/engine/processes/workchains/workchain.py	WorkChain implementation
ORM node	src/aiida/orm/nodes/node.py	Base Node class
QueryBuilder	src/aiida/orm/querybuilder.py	Query interface for the provenance graph
Process runner	src/aiida/engine/runners.py	Runner executes and submits processes
Plugin factories	src/aiida/plugins/factories.py	DataFactory, CalculationFactory, etc.
Storage ABC	src/aiida/orm/implementation/storage_backend.py	StorageBackend abstract base class
Transport ABC	src/aiida/transports/transport.py	Transport, BlockingTransport, AsyncTransport
Scheduler ABC	src/aiida/schedulers/scheduler.py	Scheduler base class

Other notable files: ProcessBuilder (engine/processes/builder.py), Computer (orm/computers.py), Config (manage/configuration/config.py), Manager (manage/manager.py), DaemonClient (engine/daemon/client.py), Profile (manage/configuration/profile.py), psql_dos backend (storage/psql_dos/backend.py), RabbitmqBroker (brokers/rabbitmq/broker.py), Repository (repository/repository.py).

Database and file storage

• ORM: SQLAlchemy. File storage: disk-objectstore. Migrations: Alembic (under src/aiida/storage/psql_dos/migrations/).
• Main backend: psql_dos (PostgreSQL + disk-objectstore). Lightweight: sqlite_dos (SQLite + disk-objectstore).

Abstract base classes (ABCs)

AiiDA defines ABCs for extensible components. To create a plugin, implement the corresponding ABC and register it as an entry point.

ABC	Location	Purpose	Entry point
Transport	aiida.transports.transport	File transfer and remote command execution	aiida.transports
Scheduler	aiida.schedulers.scheduler	HPC job scheduler interface	aiida.schedulers
Parser	aiida.parsers.parser	Parse calculation outputs	aiida.parsers
StorageBackend	aiida.orm.implementation.storage_backend	Database and file storage	aiida.storage
AbstractCode	aiida.orm.nodes.data.code.abstract	Code/executable representation	aiida.data
CalcJobImporter	aiida.engine.processes.calcjobs.importer	Import existing calculation results	aiida.calculations.importers

Quick API overview via stubs

To get a compact view of a module's public API without reading the full source (which can pollute context), generate type stubs:

uv run stubgen -p aiida.orm -o /tmp/stubs             # public API only
uv run stubgen -p aiida.orm -o /tmp/stubs --include-private  # include _private members

The generated .pyi files show only signatures, classes, and type annotations, useful for understanding an API surface quickly. stubgen ships with mypy, which is part of the pre-commit optional dependencies (uv sync --extra pre-commit or just uv sync if already installed).

Project configuration

pyproject.toml (dependencies, entry points, ruff/mypy config), uv.lock, .pre-commit-config.yaml, .readthedocs.yml, .github/workflows/, .docker/.