backupchecks/docs/technical-notes-codex.md

# Technische Notities (intern)

Laatste update: 2026-02-13

## Doel
Interne technische momentopname van de repository `backupchecks` voor snelle onboarding, troubleshooting en wijzigingsimpact.

## Repository-overzicht
- Applicatie: Flask webapp met SQLAlchemy + Flask-Migrate.
- Runtime: containerized (Docker), deploy via Docker Compose stack.
- Primaire map met broncode: `containers/backupchecks/src`.
- Project bevat daarnaast veel functionele/documentatiebestanden in `docs/` en meerdere TODO-roadmaps op rootniveau.

## Belangrijkste structuur
- `containers/backupchecks/Dockerfile`: Python 3.12-slim image, `gunicorn` start met `backend.app:create_app()`.
- `containers/backupchecks/requirements.txt`: Flask stack + Postgres driver + reporting libs (`reportlab`, `Markdown`).
- `containers/backupchecks/src/backend/app`: backend domeinlogica, routes, parsers, modellen, migraties.
- `containers/backupchecks/src/templates`: Jinja templates voor auth/main/documentation pagina's.
- `containers/backupchecks/src/static`: CSS, images, favicon.
- `deploy/backupchecks-stack.yml`: compose stack met `backupchecks`, `postgres`, `adminer`.
- `build-and-push.sh`: release/test buildscript met versiebump, tags en docker push.
- `docs/`: functioneel ontwerp, changelog, migraties, API-notities.

## Applicatie-architectuur (huidige observatie)
- Factory patroon: `create_app()` in `containers/backupchecks/src/backend/app/__init__.py`.
- Blueprints:
  - `auth_bp` voor authenticatie.
  - `main_bp` voor kernfunctionaliteit.
  - `doc_bp` voor interne documentatiepagina's.
- DB-init bij startup:
  - `db.create_all()`
  - `run_migrations()`
- Achtergrondtaak:
  - `start_auto_importer(app)` start automatische mailimport thread.
- Health endpoint:
  - `GET /health` geeft `{ "status": "ok" }`.

## Functionele verwerkingsflow
- Import:
  - Mail wordt opgehaald via Microsoft Graph API.
- Parse:
  - Parser-selectie via registry + parserimplementaties per leverancier.
- Approve:
  - Nieuwe jobs landen eerst in Inbox voor eerste klantkoppeling.
- Auto-process:
  - Vervolgmails voor bekende jobs maken automatisch `JobRun` records.
- Monitor:
  - Runs verschijnen in Daily Jobs en Run Checks.
- Review:
  - Handmatige review verwijdert items uit ongereviewde werklijst.

## Configuratie en runtime
- Config wordt uit environment opgebouwd in `containers/backupchecks/src/backend/app/config.py`.
- Belangrijke variabelen:
  - `APP_SECRET_KEY`
  - `APP_ENV`
  - `APP_PORT`
  - `POSTGRES_DB`
  - `POSTGRES_USER`
  - `POSTGRES_PASSWORD`
  - `DB_HOST`
  - `DB_PORT`
- DB URI patroon:
  - `postgresql+psycopg2://<user>:<pass>@<host>:<port>/<db>`
- Default timezone in config: `Europe/Amsterdam`.

## Datamodel (globaal)
Bestand: `containers/backupchecks/src/backend/app/models.py`
- Auth/gebruikers:
  - `User` met role(s), actieve rol in sessie.
- Systeeminstellingen:
  - `SystemSettings` met Graph/mailinstellingen, importinstellingen, UI-timezone, dashboard-policy, sandbox vlag.
  - Autotask configuratie en cachevelden zijn aanwezig.
- Logging:
  - `AuditLog` (legacy alias `AdminLog`).
- Domein:
  - `Customer`, `Job`, `Override` en veel run/ticket-gerelateerde logica in andere modules/routes.
  - Kernentiteiten uit systeemkennis: `JobRun`, `MailMessage`, ticket/remark-koppeltabellen, feedback-tabellen.

## Parserarchitectuur
- Map: `containers/backupchecks/src/backend/app/parsers/`
- Twee lagen:
  - `registry.py`:
    - matching/documentatie/zichtbaarheid op `/parsers`.
    - voorbeelden moeten generiek blijven (geen klantnamen).
  - parserbestanden (`veeam.py`, `synology.py`, etc.):
    - echte detectie en parsing.
    - leveren gestructureerde output: software, type, jobnaam, status, objecten.
- Praktijkregel:
  - patronen uitbreiden door toe te voegen, niet te vervangen (backward compatibility).

## Ticketing en Autotask (kritische regels)
- Twee ticketsporen:
  - interne tickets (`tickets`, `ticket_scopes`, `ticket_job_runs`).
  - Autotask-ticketgegevens op `job_runs` + synchronisatie met intern ticket.
- Propagatie naar nieuwe runs gebeurt via `link_open_internal_tickets_to_run`.
- Deze propagatie moet worden aangeroepen bij:
  - email-gebaseerde runcreatie (importflow),
  - gemiste-runs generatie in `routes_run_checks.py`.
- Weergavelogica:
  - link-gebaseerd via expliciete JOINs.
  - resolved tickets (`resolved_at` gezet) mogen niet meer aan nieuwe runs gekoppeld worden.
  - historische links blijven zichtbaar voor audit trail.
- Anti-patterns (niet gebruiken):
  - resolved-logica op basis van datumvergelijkingen zoals `resolved_at >= run_date`.

## UI en UX-notities
- Navbar is fixed-top met dynamische padding-correctie in de main container.
- Status-badges gebruiken semantische kleurcodes (success/warning/error/override/reviewed).
- Ticket-copy knop heeft drievoudige fallback:
  - Clipboard API,
  - `execCommand('copy')`,
  - `prompt()` fallback.

## Feedbackmodule met screenshots
- Modellen: `FeedbackItem`, `FeedbackVote`, `FeedbackReply`, `FeedbackAttachment`.
- Bijlagen:
  - meerdere uploads, typevalidatie, limiet per bestand, opslag in database (BYTEA).
- Delete-strategie:
  - soft delete als standaard,
  - permanente delete alleen admin en alleen na soft delete.

## Deployment en operations
- Stackbestand exposeert:
  - app op `8080`
  - adminer op `8081`
- Postgres persistent volume:
  - `/docker/appdata/backupchecks/backupchecks-postgres:/var/lib/postgresql/data`
- In `deploy/backupchecks-stack.yml` staan onderaan ook voorbeeld `.env` variabelen opgenomen.

## Build/release-flow
Bestand: `build-and-push.sh`
- Bump opties:
  - `1` patch, `2` minor, `3` major, `t` test.
- Release-build:
  - update `version.txt`
  - commit + tag + push
  - docker push van `:<version>`, `:dev`, `:latest`
- Test-build:
  - alleen `:dev`
  - geen commit/tag.
- Services worden ontdekt onder `containers/*` met Dockerfile-per-service.

## Technische observaties / aandachtspunten
- `README.md` is momenteel leeg; snelle instapinformatie ontbreekt.
- `LICENSE` is momenteel leeg.
- `docs/architecture.md` is momenteel leeg.
- `deploy/backupchecks-stack.yml` bevat hardcoded voorbeeldwaarden (`Changeme`), risico op foutief gebruik zonder secrets-management.
- App voert DB-init + migraties uit tijdens startup; bij grotere schemawijzigingen kan dit opstarttijd/robustness beïnvloeden.
- Er is veel functionaliteit rondom parsering en ticketing; regressierisico bij routewijzigingen is hoog zonder gerichte tests.
- Voor Autotask update-calls moet `description` expliciet behouden blijven bij updates (voorkomt ongewenste NULL-overschrijving).
- Security-hygiëne blijft belangrijk:
  - geen klantnamen in parservoorbeelden/broncode,
  - geen hardcoded credentials.

## Snelle referenties
- App entrypoint: `containers/backupchecks/src/backend/app/main.py`
- App factory: `containers/backupchecks/src/backend/app/__init__.py`
- Config: `containers/backupchecks/src/backend/app/config.py`
- Modellen: `containers/backupchecks/src/backend/app/models.py`
- Parsers: `containers/backupchecks/src/backend/app/parsers/registry.py`
- Ticketing utils: `containers/backupchecks/src/backend/app/ticketing_utils.py`
- Run checks routes: `containers/backupchecks/src/backend/app/main/routes_run_checks.py`
- Compose stack: `deploy/backupchecks-stack.yml`
- Buildscript: `build-and-push.sh`