# ab-ce/abce architecture

> Architecture diagram of the GitHub repository ab-ce/abce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ab-ce/abce
- Repository: https://github.com/ab-ce/abce

## Overview

abcEconomics is a Python platform for agent-based economic simulations. A modeler creates a Simulation and agent groups, advances rounds, and invokes agent actions; agents use platform primitives to trade goods, produce or consume, communicate, and fulfill contracts. Scheduling can be single- or multiprocess, with messages exchanged between agents and simulation data sent to logging. README-level production and consumption capabilities are represented, but their detailed implementations were not sampled; links to them are therefore limited to documented platform behavior.

Main entry points: [`abcEconomics/agent.py`](https://github.com/ab-ce/abce/blob/master/abcEconomics/agent.py) (Agent base), [`abcEconomics/__init__.py`](https://github.com/ab-ce/abce/blob/master/abcEconomics/__init__.py) (Simulation), [`abcEconomics/group.py`](https://github.com/ab-ce/abce/blob/master/abcEconomics/group.py) (Agent groups), [`abcEconomics/inventory.py`](https://github.com/ab-ce/abce/blob/master/abcEconomics/inventory.py) (Goods inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation control"]
  node_simulation["Simulation<br/>[__init__.py]"]
  node_group["Agent groups<br/>[group.py]"]
  node_single_scheduler["Single scheduler<br/>[singleprocess.py]"]
  node_multi_scheduler["Multiprocess scheduler<br/>[multiprocess.py]"]
end

subgraph group_agents["Agents and economy"]
  node_agent["Agent base<br/>[agent.py]"]
  node_firm["Firm archetype<br/>[firm.py]"]
  node_household["Household archetype<br/>[household.py]"]
  node_goods["Goods agents<br/>[goods.py]"]
  node_inventory["Goods inventory<br/>[inventory.py]"]
  node_expiring_goods["Expiring goods<br/>[expiringgood.py]"]
end

subgraph group_exchange["Exchange and communication"]
  node_trader["Trading offers<br/>[trader.py]"]
  node_messenger["Agent messaging<br/>[messenger.py]"]
  node_contracts["Contracts<br/>[contracting.py]"]
  node_flex_contracts["Flexible contracts"]
  node_contract_state["Contract state<br/>[contracts.py]"]
end

subgraph group_observability["Logging and results"]
  node_logger["Simulation logger<br/>[logger.py]"]
  node_db_writer["Database writer<br/>[db.py]"]
  node_data_store[("SQLite store<br/>[db.py]")]
  node_postprocess["Log postprocessing<br/>[postprocess.py]"]
end

node_modeler(("Modeler"))

node_modeler -->|"creates and configures"| node_simulation
node_simulation -->|"builds agents"| node_group
node_simulation -->|"selects scheduler"| node_single_scheduler
node_simulation -->|"selects scheduler"| node_multi_scheduler
node_group -->|"dispatches actions"| node_single_scheduler
node_group -->|"dispatches actions"| node_multi_scheduler
node_single_scheduler -->|"runs agent actions"| node_agent
node_multi_scheduler -->|"runs agent actions"| node_agent
node_agent -.->|"specializes as"| node_firm
node_agent -.->|"specializes as"| node_household
node_agent -.->|"specializes as"| node_goods
node_firm -->|"uses goods state"| node_inventory
node_household -->|"uses goods state"| node_inventory
node_goods -->|"uses goods state"| node_inventory
node_expiring_goods -->|"extends goods state"| node_inventory
node_agent -.->|"can trade via"| node_trader
node_agent -.->|"can message via"| node_messenger
node_trader -->|"sends offer messages"| node_messenger
node_agent -.->|"can contract via"| node_contracts
node_contracts -->|"sends contract messages"| node_messenger
node_flex_contracts -->|"uses contract state"| node_contract_state
node_contracts -->|"tracks contracts"| node_contract_state
node_simulation -->|"configures logging"| node_logger
node_group -->|"submits group logs"| node_logger
node_logger -->|"writes log data"| node_db_writer
node_db_writer -->|"persists records"| node_data_store
node_data_store -->|"provides stored results"| node_postprocess

click node_simulation "https://github.com/ab-ce/abce/blob/master/abcEconomics/__init__.py"
click node_group "https://github.com/ab-ce/abce/blob/master/abcEconomics/group.py"
click node_single_scheduler "https://github.com/ab-ce/abce/blob/master/abcEconomics/scheduler/singleprocess.py"
click node_multi_scheduler "https://github.com/ab-ce/abce/blob/master/abcEconomics/scheduler/multiprocess.py"
click node_agent "https://github.com/ab-ce/abce/blob/master/abcEconomics/agent.py"
click node_firm "https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/firm.py"
click node_household "https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/household.py"
click node_goods "https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/goods.py"
click node_inventory "https://github.com/ab-ce/abce/blob/master/abcEconomics/inventory.py"
click node_expiring_goods "https://github.com/ab-ce/abce/blob/master/abcEconomics/expiringgood.py"
click node_trader "https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/trader.py"
click node_messenger "https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/messenger.py"
click node_contracts "https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/contracting.py"
click node_flex_contracts "https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/flexiblecontracting.py"
click node_contract_state "https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/contracts.py"
click node_logger "https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/logger.py"
click node_db_writer "https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/db.py"
click node_data_store "https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/db.py"
click node_postprocess "https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/postprocess.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_simulation,node_group,node_single_scheduler,node_multi_scheduler toneBlue
class node_agent,node_firm,node_household,node_goods,node_inventory,node_expiring_goods toneAmber
class node_trader,node_messenger,node_contracts,node_flex_contracts,node_contract_state toneMint
class node_logger,node_db_writer,node_data_store,node_postprocess toneRose
class node_modeler toneIndigo
```

## Components

### Simulation control

- [Simulation](https://github.com/ab-ce/abce/blob/master/abcEconomics/__init__.py): `abcEconomics/__init__.py`
- [Agent groups](https://github.com/ab-ce/abce/blob/master/abcEconomics/group.py): `abcEconomics/group.py`
- [Single scheduler](https://github.com/ab-ce/abce/blob/master/abcEconomics/scheduler/singleprocess.py): `abcEconomics/scheduler/singleprocess.py`
- [Multiprocess scheduler](https://github.com/ab-ce/abce/blob/master/abcEconomics/scheduler/multiprocess.py): `abcEconomics/scheduler/multiprocess.py`

### Agents and economy

- [Agent base](https://github.com/ab-ce/abce/blob/master/abcEconomics/agent.py): `abcEconomics/agent.py`
- [Firm archetype](https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/firm.py): `abcEconomics/agents/firm.py`
- [Household archetype](https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/household.py): `abcEconomics/agents/household.py`
- [Goods agents](https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/goods.py): `abcEconomics/agents/goods.py`
- [Goods inventory](https://github.com/ab-ce/abce/blob/master/abcEconomics/inventory.py): `abcEconomics/inventory.py`
- [Expiring goods](https://github.com/ab-ce/abce/blob/master/abcEconomics/expiringgood.py): `abcEconomics/expiringgood.py`

### Exchange and communication

- [Trading offers](https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/trader.py): `abcEconomics/agents/trader.py`
- [Agent messaging](https://github.com/ab-ce/abce/blob/master/abcEconomics/agents/messenger.py): `abcEconomics/agents/messenger.py`
- [Contracts](https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/contracting.py): `abcEconomics/contracts/contracting.py`
- [Flexible contracts](https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/flexiblecontracting.py): `abcEconomics/contracts/flexiblecontracting.py`
- [Contract state](https://github.com/ab-ce/abce/blob/master/abcEconomics/contracts/contracts.py): `abcEconomics/contracts/contracts.py`

### Logging and results

- [Simulation logger](https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/logger.py): `abcEconomics/logger/logger.py`
- [Database writer](https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/db.py): `abcEconomics/logger/db.py`
- [SQLite store](https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/db.py): `abcEconomics/logger/db.py`
- [Log postprocessing](https://github.com/ab-ce/abce/blob/master/abcEconomics/logger/postprocess.py): `abcEconomics/logger/postprocess.py`

### Other components

- **Modeler**

## Connections

- Modeler → Simulation: creates and configures
- Simulation → Agent groups: builds agents
- Simulation → Single scheduler: selects scheduler
- Simulation → Multiprocess scheduler: selects scheduler
- Agent groups → Single scheduler: dispatches actions
- Agent groups → Multiprocess scheduler: dispatches actions
- Single scheduler → Agent base: runs agent actions
- Multiprocess scheduler → Agent base: runs agent actions
- Agent base → Firm archetype: specializes as
- Agent base → Household archetype: specializes as
- Agent base → Goods agents: specializes as
- Firm archetype → Goods inventory: uses goods state
- Household archetype → Goods inventory: uses goods state
- Goods agents → Goods inventory: uses goods state
- Expiring goods → Goods inventory: extends goods state
- Agent base → Trading offers: can trade via
- Agent base → Agent messaging: can message via
- Trading offers → Agent messaging: sends offer messages
- Agent base → Contracts: can contract via
- Contracts → Agent messaging: sends contract messages
- Flexible contracts → Contract state: uses contract state
- Contracts → Contract state: tracks contracts
- Simulation → Simulation logger: configures logging
- Agent groups → Simulation logger: submits group logs
- Simulation logger → Database writer: writes log data
- Database writer → SQLite store: persists records
- SQLite store → Log postprocessing: provides stored results