City Prompt is an interactive urban-design workspace for turning a site, planning intent, and a catalogue of building and public-realm archetypes into editable 2D plans, explorable 3D scenes, and presentation renders.
The application combines:
- a React, TypeScript, Mapbox, and Three.js frontend;
- a FastAPI backend with PostgreSQL/PostGIS, Redis, Celery, and S3-compatible storage;
- building, street, park, and plaza catalogues;
- modular LEGO assembly and RLASM source-locked 3D assets; and
- optional AI providers for document interpretation, images, 3D generation, and video.
deployment-version is the canonical working and release branch; main is
kept as a synchronized mirror of it. Long-lived pilot branches are not part of
the release workflow.
Once the local stack is running, a student can:
- create an account and project;
- locate or define a site;
- draw and edit planning zones;
- assign building, street, park, and plaza archetypes;
- generate and refine a master plan;
- inspect the design in 2D and 3D;
- use available LEGO and RLASM keeper families; and
- create optional AI renders when the relevant provider key is configured.
See the user guide for the product walkthrough and the local setup guide for a beginner-friendly installation.
- Git 2.40+ and Git LFS
- Docker Desktop with Docker Compose v2
- Node.js 20+ for frontend development
- Python 3.11 or 3.12 for backend development
For the current company review, start with the October 29 handoff runbook. It explains the exact checkout, portable asset packet, private configuration and database requirements. The commands below describe the generic development stack; they are not a verified fresh-machine installation of the current catalogue.
git lfs install
git clone https://github.com/aasedor/CityPrompt.git
cd CityPrompt
cp .env.example .env
docker compose up -d --buildOn PowerShell, create the environment file with:
Copy-Item .env.example .envSet VITE_GOOGLE_MAPS_API_KEY in .env; the current frontend refuses to start
without it. Configure GOOGLE_MAPS_API_KEY separately for backend address and
elevation services. Set MAPBOX_ACCESS_TOKEN for the fallback map tiles. AI features are
enabled only when their corresponding keys are present. Never commit .env or
paste credentials into documentation.
Open:
- application: http://localhost:5175
- API health: http://localhost:8000/health
- API documentation: http://localhost:8000/docs
- MinIO console: http://localhost:9001
The first build can take several minutes. Use docker compose ps and
docker compose logs -f to inspect startup.
For day-to-day Windows development, including linked Git worktrees:
.\scripts\start-local-city-prompt.ps1The launcher preserves the shared local database and storage containers, applies
the current additive database migrations, starts the API from the current
worktree, and starts the frontend when necessary. Its worker consumes the
default, image, maintenance and classroom-document queues; a managed Celery beat
process schedules durable image recovery. It waits for /ready, including the
recovery heartbeat when image jobs are enabled. Logs, PID files and the beat
schedule stay under ignored artifacts/local-dev/. Pass -KeepBackend only
when intentionally retaining an already-running API; workers are reused only
when their owned process and all required queue subscriptions are verified.
Keep PostgreSQL, Redis, and MinIO available, then run:
cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000In another terminal:
cd frontend
npm ci
npm run devThe direct Vite server uses http://localhost:5174.
Run these gates before integrating application changes:
cd frontend
npm ci
npm run lint
npm run type-check
npm run test -- --run
npx playwright install chromium
npm run test:e2e
npm run build
npm run check:archetype-assets
npm run check:sticker-pilot-assetscd backend
python -m pytestCompiler changes also require:
python -m pytest tools/archetype_compiler/tests/ -vThe current release checklist is in PROJECT_CHECKLIST.md.
backend/ FastAPI application, migrations, workers, and pytest suite
frontend/ React application, Vitest suite, and runtime web assets
tools/ Deterministic building and public-realm asset compilers
scripts/ Local launch, validation, and bounded generation helpers
docs/ Active product, pipeline, and quality documentation
artifacts/ Ignored local output; never commit generated review batches
Runtime archetype images belong only in:
frontend/public/archetypes/buildings/
frontend/public/archetypes/openspaces/
frontend/public/archetypes/streets/
All new building-family work must follow the canonical RLASM v6.1 method, the RLASM repository policy, and the high-quality building memory. Older Sticker Method/V98 packages are historical compatibility records, not authority for new construction or keeper promotion.
Read CONTRIBUTING.md, AGENTS.md, and CLAUDE.md before substantial work.
Report sensitive issues according to SECURITY.md.
Proprietary. All rights reserved.