dotb_ai-platform/README.md

AI Platform

New AI Platform repository scaffold. The backend and SvelteKit implementation are being developed concurrently; this document records the intended local workflow, not a claim that every command already works.

Runtime layout

• Python 3.13 backend package: src/ai_platform, served as ai_platform.main:app.
• PostgreSQL 16 with a new, project-specific Compose volume named ai_platform_pgdata.
• Alembic schema changes are applied as a one-shot Compose service before the backend starts.
• SvelteKit is a separate web image under apps/web.
• old_repo/ is archived source only and is excluded from Docker build contexts and local checks.

The local Compose stack runs one backend process. It is for development only; default credentials and loopback port mappings are not deployment settings. Keep production secrets outside .env and inject them through the deployment environment or a secrets manager.

Local setup

Copy the backend/Compose template and the separate SvelteKit server-only template. Both .env files are ignored by Git; the previous root .env is preserved under old_repo/.env as historical local data, not loaded by the rebuilt service.

cp .env.example .env
cp apps/web/.env.example apps/web/.env
make install

Start the database and run the backend and web servers in separate terminals:

make db-up
make migrate
make backend-dev
make web-dev

The local web server should call the backend through server-only configuration. Do not expose BACKEND_INTERNAL_URL, database credentials, or provider keys as browser-visible PUBLIC_* variables.

Compose can instead build and start all services, including the one-shot migration step:

docker compose up --build

The database is reachable from the host at 127.0.0.1:55432, backend at 127.0.0.1:8000, and web at 127.0.0.1:3000 by default. To discard only this new database and its data, run docker compose down -v; this does not target archived or unrelated volumes.

The local database starts with only the development database. To run tests safely, create a separate database in that same new PostgreSQL instance, then pass its URL explicitly:

docker compose exec postgres createdb -U ai_platform ai_platform_test
AI_PLATFORM_DATABASE_URL=postgresql+asyncpg://ai_platform:local-change-this-password@127.0.0.1:55432/ai_platform_test make test

make test rejects a database URL that does not contain ai_platform_test. CI provisions its own isolated PostgreSQL 16 test database.

Quality checks

The opt-in pre-commit runner is installed by make install as a project-local development dependency. Run:

make check-fast
make check

make check-fast runs the pinned Ruff and pre-commit-hooks rules. make check additionally runs Python type/import checks and tests; tests must use a separate test database, never a developer or production database. CI uses the same fast hooks and the Makefile test/check commands with an isolated PostgreSQL 16 service.

Operations notes

• Apply migrations as a release step; application startup must not migrate the database.
• /health/live is liveness; /health/ready checks readiness and PostgreSQL. The Compose backend health check waits for readiness.
• Avoid logging credentials, request payloads containing personal data, or provider responses with sensitive content.
• The Compose PostgreSQL volume is disposable development data. Backup, restore, retention, secrets, TLS, and alerting must be defined for the eventual deployment target.

The web container currently assumes package.json, bun.lock, a production SvelteKit build at build/index.js, and Bun compatibility with the selected SvelteKit adapter. Confirm those assumptions with the web implementation before treating the image as verified.