VacatureRadar/README.md

# VacatureRadar

VacatureRadar is een persoonlijke, vrijwel autonome vacature-assistent voor toegestane publieke werkgeversbronnen, publieke ATS-pagina's, RSS/Atom en vacaturemails. De applicatie verzamelt vacatures, normaliseert en dedupliceert ze, past harde filters toe, berekent een uitlegbare matchscore en bundelt de beste resultaten in een dagelijkse digest.

De repository bevat zowel een **werkende MVP-kern** als de volledige product-, architectuur-, UX-, beveiligings-, operationele en agentische overdrachtsdocumentatie om het project verder autonoom af te bouwen.

## Huidige status

Reeds geïmplementeerd:

- Django 5.2-modulaire monoliet met Nederlandstalige responsive dark/light Intelligence Cockpit;
- PostgreSQL in productie en SQLite voor lokale ontwikkeling;
- Celery-worker en scheduler via Redis;
- veilige HTTP-fetcher met domeinbeleid, redirecthercontrole, contentlimieten en SSRF-blokkering;
- JSON-LD `JobPosting`, generieke HTML-, RSS/Atom- en vacaturemailparsers;
- normalisatie, herkomstbewijs, vacatureversies en idempotente opslag;
- exacte en fuzzy deduplicatie;
- deterministische kenmerken, harde uitsluitregels en uitlegbare scoring;
- zoekprofielen met revisiehistoriek en begrensde feedbackaanpassing;
- dagelijkse digests, vacaturelevenscyclus en sollicitatiedossiers;
- optionele lokale Ollama-analyse met prompt-injectionguardrails;
- Docker Compose voor lokaal gebruik en een Unraid-variant;
- tests, fixtures, CI, back-up-/herstelscripts en healthchecks.

Nog niet als productievoltooid beschouwd:

- live broninventaris en bronvoorwaarden per concrete werkgever;
- een gekozen actuele geodataset met licentie;
- productiespecifieke secrets, mailboxcredentials, domein/TLS en containerregistry.

Deze punten staan als uitvoerbare taken in [`docs/ai/BACKLOG.yaml`](docs/ai/BACKLOG.yaml). Externe credentials blokkeren nooit de rest van het werk: taken worden met mocks en interfaces afgewerkt en daarna als `blocked-external` gedocumenteerd waar echte configuratie nodig is.

Release-productiepad:

- `./scripts/release_verify.sh` bouwt de smoke-, backup/restore- en artifactcontrole;
- [`docs/operations/UNRAID_DEPLOYMENT.md`](docs/operations/UNRAID_DEPLOYMENT.md) bevat een expliciet upgrade/rollbackpad met releaseartefacten.

## Snelste start voor Codex

Open de uitgepakte repository als project en geef Codex deze opdracht:

```text
Lees CODEX_START_HERE.md en AGENTS.md volledig. Voer daarna het autonome uitvoeringsprotocol uit. Werk alle taken met status ready in docs/ai/BACKLOG.yaml op volgorde af. Vraag geen productbeslissingen; gebruik de vastgelegde defaults. Wanneer een extern secret, account of live bronreview ontbreekt, implementeer en test de interface met fixtures, markeer uitsluitend dat externe deel als blocked-external en ga meteen door met de volgende taak. Stop pas nadat alle ready taken done zijn en scripts/codex_verify.sh volledig slaagt.
```

De repository-instructies staan in [`AGENTS.md`](AGENTS.md). De handmatige startpagina staat in [`CODEX_START_HERE.md`](CODEX_START_HERE.md).

## Lokale quickstart

Vereisten: Python 3.12 of 3.13 en `uv`.

```bash
./scripts/codex_bootstrap.sh
uv run python manage.py runserver 0.0.0.0:8080
```

Het bootstrap-script:

1. maakt alleen wanneer nodig een lokale `.env` aan;
2. installeert exact de gelockte dependencies;
3. voert migraties uit;
4. maakt demo-inhoud aan;
5. draait lint, systeemchecks, migratiecheck, tests en taakledgervalidatie.

Bij een door het script aangemaakte ontwikkelomgeving is de tijdelijke login:

```text
admin / codex-local-only
```

Gebruik die nooit buiten lokale ontwikkeling.

## Docker Compose

```bash
APP_HOST=localhost APP_SCHEME=http bash scripts/deploy_docker.sh
```

De webinterface luistert op `0.0.0.0:1226` (containerpoort `8080`). Voor een one-shot deploy kun je nu draaien:

```bash
APP_HOST=localhost APP_SCHEME=http bash scripts/deploy_docker.sh
```

De script zet ontbrekende `.env`-waarden automatisch met sterke defaults (secrets, database-wachtwoord, admin-credentials, ports) en start direct de volledige Docker-stack. Daarna:

- `http://127.0.0.1:1226/health/ready/`
- `http://127.0.0.1:1226/health/live/`

Zet voor publieke productie:
- `APP_HOST=<jouw-domein>`
- `APP_SCHEME=https`
- `DJANGO_DEBUG=0`
- `SESSION_COOKIE_SECURE=1`
- `CSRF_COOKIE_SECURE=1`
- `SECURE_SSL_REDIRECT=1`

De script blijft geen handmatige invulstappen voor compose vereisen; pas deze omgevingsvariabelen aan vóór eerste deploy.

## Push-to-deploy via Gitea

Er is een `.gitea/workflows/deploy.yml` toegevoegd voor automatisch deployen op elke push naar `main` en `master`.

Wat je nodig hebt:

- éénmalige setup van een **self-hosted Gitea-runner** op je server met Docker-toegang

Daarna doet elke push automatisch:

- checkout van de repo op de runner
- `bash scripts/deploy_docker.sh` op de server
- automatische healthcheck + `collectstatic`

De workflow verwacht geen host/SSH-repo secrets uit het Actions-configuratiescherm.

Zie [Gitea push-to-deploy](docs/operations/GITEA_DEPLOYMENT.md) voor de exacte serverconfiguratie.

## Zelf een schone overdrachts-ZIP maken

```bash
uv run python scripts/package_project.py ../VacatureRadar_Project.zip
uv run python scripts/verify_package.py ../VacatureRadar_Project.zip
```

Het packaging-script sluit `.env`, virtuele omgevingen, caches, lokale databases, logs, media en back-ups uit. In de ZIP staat `PROJECT_MANIFEST.json` met grootte en SHA-256 per bestand.

## Kwaliteitsgates

```bash
./scripts/codex_verify.sh
```

De gate vereist:

- Ruff zonder bevindingen;
- een geldige Django-configuratie;
- geen ontbrekende migraties;
- alle tests geslaagd;
- minimaal 70% branch-aware codedekking;
- een geldige machineleesbare backlog.

## Repositorykaart

```text
apps/                    Django-domeinmodules
  core/                  dashboard, health en beveiligingsheaders
  profiles/              zoekprofielen en revisies
  sources/               bronbeleid, fetcher, adapters en IMAP
  jobs/                  normalisatie, dedupe, scoring en sollicitaties
  notifications/         digest-outbox en verzending
config/                  Django/Celery-configuratie
config-data/             voorbeeldprofielen en bronbeleid
fixtures/                deterministische parser- en integratietestdata
templates/ + static/     server-rendered interface en designimplementatie
docs/                    alle product-, technische en operationele specificaties
deployment/unraid/       Unraid-installatiehandleiding
.agents/skills/          repo-eigen Codex-workflow
scripts/                 bootstrap, verificatie, back-up en beheer
tests/                   unit-, integratie- en securitytests
```

## Veiligheidsgrenzen

Vacature-inhoud, e-mailinhoud en externe HTML zijn altijd onbetrouwbare data. Ze mogen nooit instructies worden voor AI of automatisering. De applicatie:

- logt niet automatisch in op vacaturesites;
- omzeilt geen CAPTCHA, rate limit of toegangscontrole;
- scrapt denylistplatformen niet rechtstreeks;
- solliciteert nooit automatisch;
- bewaart alleen beperkte brondata en verwijdert ruwe documenten volgens retentie;
- laat harde uitsluitregels niet door een taalmodel wijzigen;
- maakt netwerktoegang opt-in per goedgekeurde bron.

Lees [`SECURITY.md`](SECURITY.md) en [`docs/quality/THREAT_MODEL.md`](docs/quality/THREAT_MODEL.md) vóór productiegebruik.

## Documentatie-ingangen

- [Projectoverdracht voor Codex](CODEX_START_HERE.md)
- [Product requirements](docs/product/PRODUCT_REQUIREMENTS.md)
- [Systeemarchitectuur](docs/architecture/SYSTEM_ARCHITECTURE.md)
- [Datamodel](docs/architecture/DATA_MODEL.md)
- [UX- en designspecificatie](docs/design/UX_SPEC.md)
- [Stitch-integratieplan en schermmapping](docs/design/STITCH_INTEGRATION_PLAN.md)
- [Bron- en adaptercontract](docs/architecture/SOURCE_ADAPTERS.md)
- [Scoringengine](docs/architecture/SCORING_ENGINE.md)
- [Unraid-deployment](docs/operations/UNRAID_DEPLOYMENT.md)
- [Runbook](docs/operations/RUNBOOK.md)
- [Teststrategie](docs/quality/TEST_STRATEGY.md)
- [Traceabilitymatrix](docs/quality/TRACEABILITY_MATRIX.md)
- [Oorspronkelijk functioneel en technisch ontwerp](docs/reference/VacatureRadar_functioneel_en_technisch_ontwerp.pdf)
- [Verificatierapport van de aangeleverde basis](VERIFICATION_REPORT.md)

## Licentie

MIT voor de broncode. Controleer voor iedere externe vacaturebron afzonderlijk de voorwaarden, robotsregels, databankrechten en toepasselijke wetgeving. Dit project levert technisch bronbeleid, maar geen juridisch advies.