admin / Apex

# Synapse-Apex v2

Bid/tender management platform that turns service documentation and tender documents
into a compliance-aligned, priced, review-ready **winning bid submission package**.
Built to the blueprint in `../Synapse-Apex/BLUEPRINT.md` (see also `DECISIONS.md`).

**v2 adds the Answer Library** — a searchable, self-populating catalogue of tender
questions and proven responses (sidebar → *Answer Library*), designed to help the team
reuse what already won and bid faster. See `docs/ANSWER_LIBRARY_BLUEPRINT.md` for the
design and roadmap. After upgrading, run **Harvest approved** in the Answer Library once
to back-fill it from existing approved responses.

📖 **Guides:** [User Guide](docs/USER_GUIDE.md) · [Admin Guide](docs/ADMIN_GUIDE.md)
(PDF versions alongside them in `docs/`).

## Quick start

```bash
cp .env.example .env
# edit .env: set a strong JWT_SECRET and (optionally) ANTHROPIC_API_KEY
docker compose up -d --build
```

Then open **http://localhost:3000** and sign in with the seeded administrator
(`ADMIN_EMAIL` / `ADMIN_INITIAL_PASSWORD` from `.env`). You will be prompted to
change the password on first login.

The backend auto-creates tables and seeds reference data on first boot:
frameworks, resource types, effort rules, licence costs and the default workflow.

### AI features

Set `ANTHROPIC_API_KEY` in `.env` to enable capability extraction, requirement
extraction, response generation and pricing justifications (default model
`claude-opus-4-8`). **With no key the app still runs** — AI steps produce clearly
labelled placeholder drafts so the whole workflow is demoable offline.

## Services

| Service   | Port | Notes |
|-----------|------|-------|
| frontend  | 3000 | React SPA (nginx), proxies `/api` to backend |
| backend   | 8000 | FastAPI (internal); OpenAPI at `/docs` |
| worker    | —    | Celery worker (document parsing + AI generation) |
| postgres  | —    | Postgres 16, volume `pgdata` |
| redis     | —    | Celery broker + result backend |

## Modules

1. **Capability library** — upload service/architecture docs → extracted capabilities with framework-aligned win responses (Capability library page).
2. **Bid response engine** — upload tender → requirement review gate → back-scheduled bid plan → grounded draft responses (bid workspace).
3. **Cost engine** — endpoint counts → effort-rule-driven resource hours → editable cost sheet.
4. **Pricing** — risk/management contingency + margin-on-price waterfall + AI justification & value statements.
5. **Resource catalogue** — resource types, rates, licences (Administration → Resources); effort rules drive Module 3.
6. **Package assembly & review** — assemble → approve/request-changes → export DOCX/XLSX/PDF.

Roles: Administrator (top), Bid Manager, Contributor, Finance, Approver, Read-Only.
MFA (TOTP) is optional per user; an admin can globally enforce it
(Administration → Security).

## Tests

```bash
docker compose run --rm backend pytest -q
```

Unit tests cover the exact-decimal cost/pricing maths and the working-day
back-scheduler.

## Backup

```bash
# Database
docker compose exec postgres pg_dump -U apex apex > backup_$(date +%F).sql
# Uploaded documents
docker run --rm -v synapse-apex_uploads:/data -v "$PWD":/backup alpine \
  tar czf /backup/uploads_$(date +%F).tgz -C /data .
```

## Project layout

```
backend/app
  core/        config, db, security, deps (RBAC), seed
  models/      SQLAlchemy tables
  schemas/     Pydantic request/response models
  routers/     auth, admin, resources, capabilities, bids, commercial, exports
  services/    ai, storage, costing (Decimal maths), scheduling
  workers/     Celery app + tasks (extraction / generation)
  ai/prompts/  versioned prompt templates
frontend/src
  pages/       Login, Dashboard, BidWorkspace, Capabilities, admin/*
  components/  Layout
  lib/         api client, auth context
```