72 lines
3.7 KiB
Markdown
72 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|