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 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

# 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

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

npm --prefix app/web/frontend run dev
npm --prefix app/web/frontend run build
npm --prefix app/web/frontend run typecheck

Python core

# 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 in the source repository.