# nbdor/elementsim architecture

> Architecture diagram of the GitHub repository nbdor/elementsim, 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/nbdor/elementsim
- Repository: https://github.com/nbdor/elementsim

## Overview

ElementSim is an early-stage FastAPI service for medieval chemistry and crafting. Its only active user-facing workflow is requesting the root or health endpoint; the versioned API router is not mounted, and simulation, crafting, recipe discovery, and skill progression are documented as planned rather than implemented. Existing SQLAlchemy models describe elements, processes, recipes, and inventories, but no execution engine connects them. The graph reflects those declarations and the configured database session; planned capability nodes use the enclosing app path because their implementations are absent.

Main entry points: [`app/db/base.py`](https://github.com/nbdor/elementsim/blob/main/app/db/base.py) (ORM base), [`app/db/session.py`](https://github.com/nbdor/elementsim/blob/main/app/db/session.py) (DB sessions), [`app/main.py`](https://github.com/nbdor/elementsim/blob/main/app/main.py) (FastAPI app), [`app/core/config.py`](https://github.com/nbdor/elementsim/blob/main/app/core/config.py) (Application settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_config["Application settings<br/>[config.py]"]
  node_router["Versioned router<br/>[api.py]"]
end

subgraph group_domain["Crafting Domain"]
  node_elements["Elements<br/>[element.py]"]
  node_processes["Processes<br/>[process.py]"]
  node_recipes["Recipes<br/>[recipe.py]"]
  node_inventory["Inventory<br/>[inventory.py]"]
  node_planned["Planned simulation"]
end

subgraph group_persistence["Persistence"]
  node_dbbase["ORM base<br/>[base.py]"]
  node_session["DB sessions<br/>[session.py]"]
end

node_caller(("API caller"))
node_database[("Configured database")]

node_caller -->|"requests endpoint"| node_app
node_app -->|"reads settings"| node_config
node_session -->|"reads connection settings"| node_config
node_session -->|"connects sessions"| node_database
node_elements -->|"maps model"| node_dbbase
node_processes -->|"maps model"| node_dbbase
node_recipes -->|"maps model"| node_dbbase
node_inventory -->|"maps model"| node_dbbase

click node_app "https://github.com/nbdor/elementsim/blob/main/app/main.py"
click node_config "https://github.com/nbdor/elementsim/blob/main/app/core/config.py"
click node_router "https://github.com/nbdor/elementsim/blob/main/app/api/v1/api.py"
click node_elements "https://github.com/nbdor/elementsim/blob/main/app/models/element.py"
click node_processes "https://github.com/nbdor/elementsim/blob/main/app/models/process.py"
click node_recipes "https://github.com/nbdor/elementsim/blob/main/app/models/recipe.py"
click node_inventory "https://github.com/nbdor/elementsim/blob/main/app/models/inventory.py"
click node_planned "https://github.com/nbdor/elementsim/tree/main/app"
click node_dbbase "https://github.com/nbdor/elementsim/blob/main/app/db/base.py"
click node_session "https://github.com/nbdor/elementsim/blob/main/app/db/session.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_app,node_config,node_router toneBlue
class node_elements,node_processes,node_recipes,node_inventory,node_planned,node_database toneAmber
class node_dbbase,node_session,node_caller toneMint
```

## Components

### Service API

- [FastAPI app](https://github.com/nbdor/elementsim/blob/main/app/main.py): `app/main.py`
- [Application settings](https://github.com/nbdor/elementsim/blob/main/app/core/config.py): `app/core/config.py`
- [Versioned router](https://github.com/nbdor/elementsim/blob/main/app/api/v1/api.py): `app/api/v1/api.py`

### Crafting Domain

- [Elements](https://github.com/nbdor/elementsim/blob/main/app/models/element.py): `app/models/element.py`
- [Processes](https://github.com/nbdor/elementsim/blob/main/app/models/process.py): `app/models/process.py`
- [Recipes](https://github.com/nbdor/elementsim/blob/main/app/models/recipe.py): `app/models/recipe.py`
- [Inventory](https://github.com/nbdor/elementsim/blob/main/app/models/inventory.py): `app/models/inventory.py`
- [Planned simulation](https://github.com/nbdor/elementsim/tree/main/app): `app`

### Persistence

- [ORM base](https://github.com/nbdor/elementsim/blob/main/app/db/base.py): `app/db/base.py`
- [DB sessions](https://github.com/nbdor/elementsim/blob/main/app/db/session.py): `app/db/session.py`

### Other components

- **API caller**
- **Configured database**

## Connections

- API caller → FastAPI app: requests endpoint
- FastAPI app → Application settings: reads settings
- DB sessions → Application settings: reads connection settings
- DB sessions → Configured database: connects sessions
- Elements → ORM base: maps model
- Processes → ORM base: maps model
- Recipes → ORM base: maps model
- Inventory → ORM base: maps model