> ## Documentation Index
> Fetch the complete documentation index at: https://artemiscity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

> How the Artemis City repository is split into a Python core, an Express API, a React dashboard, and archived legacy surfaces — with the manifests and commands for each.

Artemis City is a single git repository that holds several projects with distinct runtimes and package managers. Each project has its own manifest so you can build, test, and deploy it independently without pulling the rest of the tree into scope.

## When to use this

* You are cloning the repo for the first time and want to know which directory holds the code you need.
* You are running a build, typecheck, or test command and are unsure which manifest owns it.
* You are extending the API, frontend, or Python core and want to know where to add code and dependencies.

If you only need to run the platform end-to-end, see [Environments](/Documentation/operations/environments) and skip to the top-level scripts.

## Project map

| Project                   | Path                | Runtime                 | Manifest                                        | Purpose                                                                 |
| ------------------------- | ------------------- | ----------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
| Python core               | `src/`              | Python 3.12             | Root `pyproject.toml`, `requirements.txt`       | Kernel, agents, memory, governance, ATP — the authoritative core.       |
| In-process kernel         | `app/kernel/`       | Python 3.12             | Ships with the Python core wheel                | Kernel CLI and in-process agent router.                                 |
| FastAPI dashboard backend | `app/api/main.py`   | Python / FastAPI        | Root `pyproject.toml`                           | Serves the React dashboard on `/api/*`.                                 |
| Express API               | `app/api/**/*.ts`   | Node 20+ / TypeScript   | `app/api/package.json`, `app/api/tsconfig.json` | Public HTTP boundary (`/api/v1/*`) that bridges to the Python core.     |
| React dashboard           | `app/web/frontend/` | Node 20+ / Vite / React | `app/web/frontend/package.json`                 | Operator dashboard. Proxies `/api/*` to the FastAPI backend during dev. |
| Launch demos              | `src/launch/`       | Python scripts          | `src/launch/requirements.txt`                   | CLI walkthroughs and demo entry points.                                 |
| Concept demos             | `Concept_Demos/`    | Static HTML             | `Concept_Demos/README.md`                       | Standalone browser demos.                                               |

The root `package.json` is a **workspace coordinator**, not a service manifest. It registers `app/api` and `app/web/frontend` as npm workspaces and exposes convenience scripts that delegate into each workspace.

## Manifest ownership

Package definitions live with the project they describe. There is exactly one canonical manifest per runtime:

* **Python** — the root `pyproject.toml` is the canonical package manifest. `src/pyproject.toml` is a pointer-only stub kept for older scripts and docs; do not treat it as a build target.
* **Express API** — `app/api/package.json` and `app/api/tsconfig.json` own the API's dependencies and TypeScript config. `app/api/package-lock.json` is generated from that manifest.
* **React frontend** — `app/web/frontend/package.json` owns the dashboard's dependencies and Vite/TypeScript config.
* **Workspace root** — the root `package.json` only lists workspaces, cross-project scripts, and shared devtools. Do not add API- or frontend-specific dependencies here.

## Common commands

Run these from the repository root unless noted otherwise.

### Root workspace

```bash theme={null}
# Typecheck both the Express API and the React frontend
npm run typecheck

# Build both projects
npm run build

# Start the Express API in dev mode
npm run dev

# Run the Express API test suite
npm test
```

### Express API only

```bash theme={null}
npm --prefix app/api run build
npm --prefix app/api run dev
npm --prefix app/api run typecheck
npm --prefix app/api run test
```

### React frontend only

```bash theme={null}
npm --prefix app/web/frontend run dev
npm --prefix app/web/frontend run build
npm --prefix app/web/frontend run typecheck
```

### Python core

```bash theme={null}
# Test suite (canonical)
uv run --with pytest python -m pytest src/tests

# Kernel smoke test used by the promote workflow
uv run --with pytest python -m pytest src/tests/test_kernel_smoke.py -q

# Build the Python wheel from the root manifest
uv run --with build --with hatchling python -m build --wheel --no-isolation
```

## Cross-project boundaries

Keep these boundaries intact when adding code:

* The Express API calls the Python core through `app/api/lib/pythonBridge.ts` and `src/api_bridge.py`. It should not reimplement Python logic.
* The React dashboard talks to the FastAPI backend on `/api/*`, not the Express `/api/v1/*` surface.
* The Python wheel packages `src/` and `app/kernel/`. It does **not** package `app/api`, `app/web`, or `app/scripts`.
* Environment files (`.env`, `app/api/.env`, `src/.env`) are coordinated by `setup_secrets.sh`. Preserve that flow when adding new secrets.

## Archived and migration-only surfaces

Some directories are retained for reference or migration. Do not build new features on top of them:

* **`archive/legacy-web-api/`** — the previous `app/web/api/` FastAPI copy. Replaced by `app/api/main.py`. Kept for reference only.
* **`tests/`** (root) — legacy pytest tree. The canonical suite is `src/tests/`. Add new tests under `src/tests/`, not here.
* **`src/Kernel/`** — placeholder that predates `app/kernel/`. The maintained kernel is `app/kernel/`.
* **`memory/`** — mirrors `src/memory/` outside the package root. Kept as a compatibility shim; do not extend it.

The full map, including stale shells and cross-project coupling rules, lives at [`docs/PROJECT_BOUNDARIES.md`](https://github.com/AgenticGovernace/AgenticGovernance-ArtemisCity/blob/prod/docs/PROJECT_BOUNDARIES.md) in the source repository.


## Related topics

- [Memory Structure](/Documentation/memory/hybrid-memory-bus.md)
- [Graphical Knowledge View](/Documentation/integrations/obsidian-supabase.md)
- [LIVING_CITY](/Documentation/Introduction/LIVING_CITY.md)
- [What Is Artemis City?](/Documentation/Introduction/what-is-artemis-city.md)
- [Embodied Cognition](/Documentation/concepts/embodied-cognition.md)