planet/CODEMAP.md

Code Map

This map gives agents and maintainers a quick orientation without replacing the deeper architecture docs. Current implementation docs under docs/technical/ are the source of detail for specific subsystems.

Top-Level Areas

Path	Role	Notes
backend/	FastAPI backend, auth, APIs, data collectors, AI task orchestration, persistence	Tests live in backend/tests/; run backend tests from backend/ with the root uv project.
frontend/	React admin console, Docs UI, Web Earth shell, Vite build	Use Bun only. Public Earth assets live under frontend/public/earth/.
aiprovider/	Model provider/protocol adapter service	Keep it free of product-specific prompts and workflows.
motion_agent/	Motion capture protocol service used by planet.sh	Often dry-runs when cameras are unavailable, especially in WSL.
scripts/	Utility scripts and harness wrappers	Harness commands live in scripts/harness/.
docs/	Plans, technical docs, changelog, harness docs	Public technical docs are explicitly registered by the frontend Docs catalog.
deploy/helm/planet/	Helm chart for staging/deployment smoke paths	CI runs helm lint/template when delivery checks are available.
.gitea/workflows/	CI, release image build, staging deploy workflows	This repository uses Gitea workflow files, not .github/workflows/.
planet.sh	Main local lifecycle script	Owns init/start/restart/stop/health/log/createuser/destroy.

Runtime Entry Points

Runtime	Entry Point	Validation
Local full stack	./planet.sh start	./planet.sh health
Backend API	backend/app/main.py	cd backend && uv run --frozen --group dev --project .. python -m pytest -q
Frontend app	frontend/src/main.tsx and frontend/vite.config.mts	cd frontend && bun run build
AI Provider	aiprovider/main.py	curl http://localhost:8010/health after startup
Motion Agent	python -m motion_agent via planet.sh	./planet.sh health or dry-run startup
Docs UI	frontend/src/pages/Docs/	Docs catalog metadata plus frontend build

Ownership Boundaries

• Backend owns business state, auth, evidence collection, prompt selection, AI task orchestration, and database persistence.
• aiprovider owns provider identity, request adapter style, model gateway retries, and health/status endpoints only.
• Frontend owns operator workflows, Docs presentation, Web Earth orchestration, and client-side state that mirrors backend truth.
• Web Earth rendering changes must preserve documented layer order, altitude offsets, picking behavior, legend semantics, and performance constraints.
• planet.sh owns local environment bootstrap and service lifecycle. Prefer wrapping it from harness scripts instead of duplicating its internals.
• Harness scripts source scripts/harness/lib.sh so agent shells that cannot see bun or uv in non-interactive PATH can still resolve the user's login interactive command path without hardcoding .zshrc.

Validation Commands

scripts/harness/doctor.sh
scripts/harness/security-check.sh
scripts/harness/backend-rules-check.sh
scripts/harness/frontend-rules-check.sh
scripts/harness/docs-consistency-check.sh
scripts/harness/quick-check.sh
scripts/harness/validate.sh
./planet.sh health

CI-equivalent local checks:

cd backend
uv run --frozen --group dev --project .. python -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q

cd frontend
bun install --frozen-lockfile
bun run build
PLANET_FRONTEND_SMOKE_URL=http://127.0.0.1:4173 bun ../scripts/harness/frontend-smoke.mjs

The frontend smoke covers public routes, unauthenticated admin guards, login-error handling, the Earth iframe entry, and authenticated super_admin admin route/section rendering with mocked API data. Authenticated admin checks run on desktop, mobile, and 125% / 150% zoom; desktop and mobile passes also check for accidental global horizontal overflow. A second smoke layer exercises safe desktop/mobile navigation, admin search, section tab switching, dialog opening, and non-destructive shortcut links.

Optional delivery smoke, when Docker and Helm are available:

PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh

Deeper Docs

Topic	Start Here
Data products and flows	docs/technical/zh/platform-data-flows.md and docs/technical/en/platform-data-flows.md
Operations and local lifecycle	docs/technical/zh/ops-runbook.md and docs/technical/en/ops-runbook.md
planet.sh startup behavior	docs/technical/zh/ops-planet-sh-startup.md and docs/technical/en/ops-planet-sh-startup.md
AI Provider	docs/technical/zh/agents-aiprovider.md and docs/technical/en/agents-aiprovider.md
Admin frontend	docs/technical/zh/frontend-admin-frontend-context.md and docs/technical/en/frontend-admin-frontend-context.md
Earth frontend	docs/technical/zh/earth-frontend-context.md and docs/technical/en/earth-frontend-context.md
Earth render order	docs/technical/zh/earth-render-layer-order.md and docs/technical/en/earth-render-layer-order.md
Documentation rules	docs/documentation-coverage-rules.md
Harness workflow	docs/HARNESS.md

Known Sharp Edges

• project_context.md is static background for agents. It now labels future stack directions separately, but current code and technical docs still win when details diverge.
• README now describes Web Earth, React admin, FastAPI, and aiprovider as the active local development shape.
• Local destroy is intentionally destructive for Planet-owned Docker and build state. Never run it as a validation shortcut.