# Prototype Deployment

This repo is currently set up to run as a single-host prototype with Docker Compose.

## What This Includes

- `platform-service`
- `extraction-service`
- `mcp-server`
- `cosmos-emulator`
- `azurite`
- `mailpit`
- `gateway` (Traefik)
- `loki`
- `grafana`

## What Stays External

- Azure Key Vault if you choose to use it
- Any real API credentials such as Stripe or Gemini

For this VM prototype, Cosmos is self-hosted through the Linux Cosmos DB Emulator container. Everything else should still stay in `.env` and move to a real secret manager later.
Blob/file uploads are self-hosted through Azurite.
Prototype email delivery is self-hosted through Mailpit.

## First-Time Setup

```bash
cp .env.example .env
```

Fill in at least:

- `JWT_SECRET`

If you want extraction features that call Gemini, also set:

- `GEMINI_API_KEY`

If you access generated blob SAS URLs from outside the VM, change `AZURE_BLOB_PUBLIC_ENDPOINT` to a host or IP that your browser can reach.

## Start The Stack

```bash
./scripts/prototype-up.sh
```

That script will:

1. Validate the required environment variables.
2. Start the local Cosmos DB emulator.
3. Start Azurite with a persistent Docker volume for blob data.
4. Build and start the rest of the Compose stack.

## Day-To-Day Commands

```bash
docker compose ps
docker compose logs -f platform-service
docker compose logs -f extraction-service
docker compose logs -f mcp-server
docker compose logs -f cosmos-emulator
docker compose logs -f azurite
docker compose logs -f mailpit
pnpm prototype:self-test
./scripts/prototype-self-test.sh
docker compose down
pnpm docker:clean
```

`pnpm prototype:self-test` is the stable host-side smoke-test entrypoint. It runs the same end-to-end check as the underlying shell script, but gives ops a single repo-level command to remember.

`pnpm docker:clean` opens an interactive Docker cleanup menu. Use it for escalating cleanup levels from status-only and compose shutdown through repo volume cleanup, image pruning, and full Docker volume pruning.

The Cosmos Data Explorer is exposed on `http://localhost:1234`.
Azurite Blob Storage is exposed on `http://localhost:10000`.
Mailpit SMTP listens on `localhost:1025` and the Mailpit inbox UI is exposed on `http://localhost:8025`.
The platform dependency health JSON is exposed on `http://localhost:4003/api/health/dependencies`.
The platform self-test page is exposed on `http://localhost:4003/api/self-test`.
The platform self-test JSON is exposed on `http://localhost:4003/api/self-test.json`.

## Notes

- This is intended for early prototype use on a single machine.
- Do not commit `.env`.
- The Linux emulator is a preview and is only appropriate for local or prototype use.
- Azurite data is persisted in the Docker volume `azurite-data`.
- When the project moves to a more secure environment later, replace the emulator with a real Azure Cosmos DB account and move secrets out of `.env` into a proper secret manager.
