This page lists the top-level folders and files of the Cluster ERP repository and says what each holds. It is a lookup table for finding code. It does not explain how the parts work together; see the architecture overview for that.
Scope and source¶
The lists were produced by listing the repository root and each named folder at commit 92f8051. Counts state their method in the table.
- Defined in: the repository tree
- Count: 15 source folder rows, 1 CI folder, 5 runtime or personal folders, and 11 root file rows
Source folders¶
These folders hold product code, tests, deployment files, or documentation.
| Folder | What it holds | Count and method | Source |
|---|---|---|---|
src/cluster_erp/ |
The Python package: ai/, config/, core/, desktop/, modules/, server/ |
28 module folders in modules/ (ls, excluding __pycache__) |
pyproject.toml:90-91 |
src/cluster_erp/ai/ |
The intent engine, tokenizer, vectorizer, and English and Turkish intent corpora | 5 files (ls, excluding __init__.py and __pycache__) |
src/cluster_erp/ai/intent_engine.py |
src/cluster_erp/core/ |
The platform core used by every module | 47 *.py files including __init__.py (ls) |
src/cluster_erp/core/__init__.py |
src/cluster_erp/server/ |
The FastAPI app factory, middleware, error handlers, shared routes, and operator command-line tools | 21 *.py files including __init__.py, 10 route files in routes/ (excluding __init__.py), 1 module in services/ (ls) |
src/cluster_erp/server/app.py |
src/cluster_erp/desktop/ |
The PySide6 desktop client | 7 module folders in desktop/modules/ (ls) |
src/cluster_erp/desktop/main.py |
webapp/ |
The metadata-driven web app served at /app: index.html, operator.html, js/, css/, i18n/, fonts/, assets/, store/ |
52 entries in js/, 26 entries in store/ (ls) |
src/cluster_erp/server/app.py:1633-1644 |
web-client/ |
Playwright end-to-end suites, the battery runner, probes, and a Vite React project | 197 _e2e_*.mjs suites (ls) |
web-client/_run_battery.mjs |
gated_apps/ |
App bundles that reach the client only through the app store | 9 folders, each with app.js (ls gated_apps/*/app.js) |
gated_apps/ |
migrations/ |
The Alembic environment and revisions | 218 *.py files in versions/ (ls) |
alembic.ini:2 |
deploy/ |
Linux node installation, service unit, process manager configuration, reverse proxy example, PostgreSQL roles and tuning, cron file, container files | 11 files and the docker/ folder (ls) |
deploy/README.md |
tests/ |
Pytest suites | 106 test_*.py files (ls) |
tests/test_architecture_boundaries.py |
scripts/ |
Backup scripts in backup/ and two maintenance scripts |
6 files in backup/, 2 scripts at the top (ls) |
scripts/backup/ |
tools/ |
Developer tools | 3 files (ls) |
tools/ |
installer/ |
The Windows installer script and setup wizard | 2 files (ls) |
installer/cluster_erp_setup.iss |
docs/ |
Historical plans, audits, research, and this wiki in docs/wiki/ |
62 entries at the top level (ls) |
docs/wiki/README.md |
Documents in docs/ outside docs/wiki/ are historical. The wiki does not cite them as sources (see the documentation standard).
Continuous integration¶
| Folder | What it holds | Count and method | Source |
|---|---|---|---|
.github/workflows/ |
The CI workflow | 1 file, ci.yml (ls) |
.github/workflows/ci.yml |
Runtime and personal folders¶
These folders exist in the working tree but are not product source. Their contents are not documented.
| Folder | What it is | Count and method | Source |
|---|---|---|---|
data/ |
Runtime data of a local server | Not counted | src/cluster_erp/config/settings.py:348 |
_shots/ |
Screenshots from probes | Not counted | _shots/ |
reports/ |
Generated reports | Not counted | reports/ |
research_notes/ |
Personal research notes | Not counted | research_notes/ |
graphify-out/ |
Generated output of a graph tool | Not counted | graphify-out/ |
Root files¶
| File | What it holds | Source |
|---|---|---|
pyproject.toml |
Package metadata, dependencies, the desktop extra, console scripts, Ruff and mypy configuration |
pyproject.toml:5-10, pyproject.toml:86-88 |
alembic.ini |
Alembic configuration; script_location = migrations |
alembic.ini:2 |
requirements.lock and uv.lock |
Pinned dependency sets (not read for this page) | requirements.lock |
| internal rulebook (not published) | Project rules and intent for contributors | internal rulebook (not published) |
CHANGELOG.md |
Release notes | CHANGELOG.md |
LICENSE |
The proprietary license text | LICENSE |
README.md |
Repository readme | README.md |
INSTALL.bat and README_INSTALL.txt |
Windows installation helpers | INSTALL.bat |
start_desktop.bat |
Windows launcher for the desktop client | start_desktop.bat |
.env.example |
Example environment variable names (values are not reproduced) | .env.example |
.gitignore, .gitattributes, .dockerignore |
Repository and container build settings | .gitignore |
Root-level *.log and *.png files are local artefacts and are not documented.
Constraints and validation¶
- The Alembic folder is
migrations/(alembic.ini:2).migrations/env.pyimports every module'smodelspackage to build the target metadata (migrations/env.py:76-86). - The server finds the web app at
<repository root>/webapp(src/cluster_erp/server/app.py:1633). It mounts it only when the folder exists (src/cluster_erp/server/app.py:1634). - Whether the Vite React project in
web-client/srcis in use is not determined from code.web-client/README.mdis the stock Vite template text.
Related pages¶
Verified against commit 92f8051 on 2026-11-13.