// Use when exploring the aiida-core codebase structure, looking for key files, or understanding how packages relate to each other.
Use when adding a new `verdi` subcommand in `src/aiida/cmdline/`.
Use when adding a new third-party dependency to aiida-core's `pyproject.toml`.
Use when making commits, creating branches, or preparing pull requests for aiida-core.
Use when diagnosing failed, stuck, or misbehaving AiiDA processes or the daemon.
Use when deprecating a public Python API or `verdi` CLI command in aiida-core.
Use when running pre-commit, linting, type checking, or fixing CI failures in aiida-core.
| name | architecture-overview |
| description | Use when exploring the aiida-core codebase structure, looking for key files, or understanding how packages relate to each other. |
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 |
| 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).
src/aiida/storage/psql_dos/migrations/).psql_dos (PostgreSQL + disk-objectstore). Lightweight: sqlite_dos (SQLite + disk-objectstore).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 |
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).
pyproject.toml (dependencies, entry points, ruff/mypy config), uv.lock, .pre-commit-config.yaml, .readthedocs.yml, .github/workflows/, .docker/.