ivooskamp/backupchecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Convert technical notes to English

Browse Source
This commit is contained in:
Ivo Oskamp 2026-02-13 13:20:19 +01:00
parent d2cdd34541
commit 084c91945a
2 changed files with 116 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/changelog-claude.md
View File

@ -7,6 +7,9 @@ This file documents all changes made to this project via Claude Code.
### Added ### Added
- Added internal technical reference document `docs/technical-notes-codex.md` with repository structure, application architecture, processing flow, parser system rules, ticketing/Autotask constraints, feedback attachment notes, deployment/build workflow, and operational attention points - Added internal technical reference document `docs/technical-notes-codex.md` with repository structure, application architecture, processing flow, parser system rules, ticketing/Autotask constraints, feedback attachment notes, deployment/build workflow, and operational attention points
### Changed
- Changed `docs/technical-notes-codex.md` language from Dutch to English to align with project language rules for documentation
### Fixed ### Fixed
- Fixed Autotask tickets and internal tickets not being linked to missed runs by calling `link_open_internal_tickets_to_run` after creating missed JobRun records in `_ensure_missed_runs_for_job` (both weekly and monthly schedules), ensuring missed runs now receive the same ticket propagation as email-based runs - Fixed Autotask tickets and internal tickets not being linked to missed runs by calling `link_open_internal_tickets_to_run` after creating missed JobRun records in `_ensure_missed_runs_for_job` (both weekly and monthly schedules), ensuring missed runs now receive the same ticket propagation as email-based runs
- Fixed checkboxes being automatically re-selected after delete actions on Inbox and Run Checks pages by adding `autocomplete="off"` attribute to all checkboxes, preventing browser from restoring previous checkbox states after page reload - Fixed checkboxes being automatically re-selected after delete actions on Inbox and Run Checks pages by adding `autocomplete="off"` attribute to all checkboxes, preventing browser from restoring previous checkbox states after page reload

224
docs/technical-notes-codex.md
View File

@ -1,57 +1,57 @@
# Technische Notities (intern) # Technical Notes (Internal)
Laatste update: 2026-02-13 Last updated: 2026-02-13
## Doel ## Purpose
Interne technische momentopname van de repository `backupchecks` voor snelle onboarding, troubleshooting en wijzigingsimpact. Internal technical snapshot of the `backupchecks` repository for faster onboarding, troubleshooting, and change impact analysis.
## Repository-overzicht ## Repository Overview
- Applicatie: Flask webapp met SQLAlchemy + Flask-Migrate. - Application: Flask web app with SQLAlchemy and Flask-Migrate.
- Runtime: containerized (Docker), deploy via Docker Compose stack. - Runtime: Containerized (Docker), deployed via Docker Compose stack.
- Primaire map met broncode: `containers/backupchecks/src`. - Primary source code location: `containers/backupchecks/src`.
- Project bevat daarnaast veel functionele/documentatiebestanden in `docs/` en meerdere TODO-roadmaps op rootniveau. - The project also contains extensive functional documentation in `docs/` and multiple roadmap TODO files at repository root.
## Belangrijkste structuur ## Main Structure
- `containers/backupchecks/Dockerfile`: Python 3.12-slim image, `gunicorn` start met `backend.app:create_app()`. - `containers/backupchecks/Dockerfile`: Python 3.12-slim image, starts `gunicorn` with `backend.app:create_app()`.
- `containers/backupchecks/requirements.txt`: Flask stack + Postgres driver + reporting libs (`reportlab`, `Markdown`). - `containers/backupchecks/requirements.txt`: Flask stack + PostgreSQL driver + reporting libraries (`reportlab`, `Markdown`).
- `containers/backupchecks/src/backend/app`: backend domeinlogica, routes, parsers, modellen, migraties. - `containers/backupchecks/src/backend/app`: backend domain logic, routes, parsers, models, migrations.
- `containers/backupchecks/src/templates`: Jinja templates voor auth/main/documentation pagina's. - `containers/backupchecks/src/templates`: Jinja templates for auth/main/documentation pages.
- `containers/backupchecks/src/static`: CSS, images, favicon. - `containers/backupchecks/src/static`: CSS, images, favicon.
- `deploy/backupchecks-stack.yml`: compose stack met `backupchecks`, `postgres`, `adminer`. - `deploy/backupchecks-stack.yml`: compose stack with `backupchecks`, `postgres`, `adminer`.
- `build-and-push.sh`: release/test buildscript met versiebump, tags en docker push. - `build-and-push.sh`: release/test build script with version bumping, tags, and image push.
- `docs/`: functioneel ontwerp, changelog, migraties, API-notities. - `docs/`: functional design, changelogs, migration notes, API notes.
## Applicatie-architectuur (huidige observatie) ## Application Architecture (Current Observation)
- Factory patroon: `create_app()` in `containers/backupchecks/src/backend/app/__init__.py`. - Factory pattern: `create_app()` in `containers/backupchecks/src/backend/app/__init__.py`.
- Blueprints: - Blueprints:
- `auth_bp` voor authenticatie. - `auth_bp` for authentication.
- `main_bp` voor kernfunctionaliteit. - `main_bp` for core functionality.
- `doc_bp` voor interne documentatiepagina's. - `doc_bp` for internal documentation pages.
- DB-init bij startup: - Database initialization at startup:
- `db.create_all()` - `db.create_all()`
- `run_migrations()` - `run_migrations()`
- Achtergrondtaak: - Background task:
- `start_auto_importer(app)` start automatische mailimport thread. - `start_auto_importer(app)` starts the automatic mail importer thread.
- Health endpoint: - Health endpoint:
- `GET /health` geeft `{ "status": "ok" }`. - `GET /health` returns `{ "status": "ok" }`.
## Functionele verwerkingsflow ## Functional Processing Flow
- Import: - Import:
- Mail wordt opgehaald via Microsoft Graph API. - Email is fetched via Microsoft Graph API.
- Parse: - Parse:
- Parser-selectie via registry + parserimplementaties per leverancier. - Parser selection through registry + software-specific parser implementations.
- Approve: - Approve:
- Nieuwe jobs landen eerst in Inbox voor eerste klantkoppeling. - New jobs first appear in Inbox for initial customer assignment.
- Auto-process: - Auto-process:
- Vervolgmails voor bekende jobs maken automatisch `JobRun` records. - Subsequent emails for known jobs automatically create `JobRun` records.
- Monitor: - Monitor:
- Runs verschijnen in Daily Jobs en Run Checks. - Runs appear in Daily Jobs and Run Checks.
- Review: - Review:
- Handmatige review verwijdert items uit ongereviewde werklijst. - Manual review removes items from the unreviewed operational queue.
## Configuratie en runtime ## Configuration and Runtime
- Config wordt uit environment opgebouwd in `containers/backupchecks/src/backend/app/config.py`. - Config is built from environment variables in `containers/backupchecks/src/backend/app/config.py`.
- Belangrijke variabelen: - Important variables:
- `APP_SECRET_KEY` - `APP_SECRET_KEY`
- `APP_ENV` - `APP_ENV`
- `APP_PORT` - `APP_PORT`
@ -60,106 +60,106 @@ Interne technische momentopname van de repository `backupchecks` voor snelle onb
- `POSTGRES_PASSWORD` - `POSTGRES_PASSWORD`
- `DB_HOST` - `DB_HOST`
- `DB_PORT` - `DB_PORT`
- DB URI patroon: - Database URI pattern:
- `postgresql+psycopg2://<user>:<pass>@<host>:<port>/<db>` - `postgresql+psycopg2://<user>:<pass>@<host>:<port>/<db>`
- Default timezone in config: `Europe/Amsterdam`. - Default timezone in config: `Europe/Amsterdam`.
## Datamodel (globaal) ## Data Model (High-level)
Bestand: `containers/backupchecks/src/backend/app/models.py` File: `containers/backupchecks/src/backend/app/models.py`
- Auth/gebruikers: - Auth/users:
- `User` met role(s), actieve rol in sessie. - `User` with role(s), active role in session.
- Systeeminstellingen: - System settings:
- `SystemSettings` met Graph/mailinstellingen, importinstellingen, UI-timezone, dashboard-policy, sandbox vlag. - `SystemSettings` with Graph/mail settings, import settings, UI timezone, dashboard policy, sandbox flag.
- Autotask configuratie en cachevelden zijn aanwezig. - Autotask configuration and cache fields are present.
- Logging: - Logging:
- `AuditLog` (legacy alias `AdminLog`). - `AuditLog` (legacy alias `AdminLog`).
- Domein: - Domain:
- `Customer`, `Job`, `Override` en veel run/ticket-gerelateerde logica in andere modules/routes. - `Customer`, `Job`, `Override`, plus extensive run/ticket logic in other modules/routes.
- Kernentiteiten uit systeemkennis: `JobRun`, `MailMessage`, ticket/remark-koppeltabellen, feedback-tabellen. - Core entities from system knowledge include `JobRun`, `MailMessage`, ticket/remark link tables, and feedback tables.
## Parserarchitectuur ## Parser Architecture
- Map: `containers/backupchecks/src/backend/app/parsers/` - Folder: `containers/backupchecks/src/backend/app/parsers/`
- Twee lagen: - Two layers:
- `registry.py`: - `registry.py`:
- matching/documentatie/zichtbaarheid op `/parsers`. - matching/documentation/visibility on `/parsers`.
- voorbeelden moeten generiek blijven (geen klantnamen). - examples must stay generic (no customer names).
- parserbestanden (`veeam.py`, `synology.py`, etc.): - parser files (`veeam.py`, `synology.py`, etc.):
- echte detectie en parsing. - actual detection and parsing logic.
- leveren gestructureerde output: software, type, jobnaam, status, objecten. - return structured output: software, type, job name, status, objects.
- Praktijkregel: - Practical rule:
- patronen uitbreiden door toe te voegen, niet te vervangen (backward compatibility). - extend patterns by adding, not replacing (backward compatibility).
## Ticketing en Autotask (kritische regels) ## Ticketing and Autotask (Critical Rules)
- Twee ticketsporen: - Two ticket tracks:
- interne tickets (`tickets`, `ticket_scopes`, `ticket_job_runs`). - internal tickets (`tickets`, `ticket_scopes`, `ticket_job_runs`).
- Autotask-ticketgegevens op `job_runs` + synchronisatie met intern ticket. - Autotask ticket fields on `job_runs` + synchronization with internal ticket records.
- Propagatie naar nieuwe runs gebeurt via `link_open_internal_tickets_to_run`. - Propagation to new runs is handled by `link_open_internal_tickets_to_run`.
- Deze propagatie moet worden aangeroepen bij: - This propagation must be called for:
- email-gebaseerde runcreatie (importflow), - email-based run creation (import flow),
- gemiste-runs generatie in `routes_run_checks.py`. - missed-run generation in `routes_run_checks.py`.
- Weergavelogica: - Display logic:
- link-gebaseerd via expliciete JOINs. - link-based via explicit JOIN queries.
- resolved tickets (`resolved_at` gezet) mogen niet meer aan nieuwe runs gekoppeld worden. - resolved tickets (`resolved_at` set) must no longer be linked to new runs.
- historische links blijven zichtbaar voor audit trail. - historical links remain visible for audit trail.
- Anti-patterns (niet gebruiken): - Anti-patterns (do not use):
- resolved-logica op basis van datumvergelijkingen zoals `resolved_at >= run_date`. - date-based resolved logic like `resolved_at >= run_date`.
## UI en UX-notities ## UI and UX Notes
- Navbar is fixed-top met dynamische padding-correctie in de main container. - Navbar is fixed-top with dynamic main container padding correction.
- Status-badges gebruiken semantische kleurcodes (success/warning/error/override/reviewed). - Status badges use semantic color coding (success/warning/error/override/reviewed).
- Ticket-copy knop heeft drievoudige fallback: - Ticket copy button uses a three-level fallback:
- Clipboard API, - Clipboard API,
- `execCommand('copy')`, - `execCommand('copy')`,
- `prompt()` fallback. - `prompt()` fallback.
## Feedbackmodule met screenshots ## Feedback Module with Screenshots
- Modellen: `FeedbackItem`, `FeedbackVote`, `FeedbackReply`, `FeedbackAttachment`. - Models: `FeedbackItem`, `FeedbackVote`, `FeedbackReply`, `FeedbackAttachment`.
- Bijlagen: - Attachments:
- meerdere uploads, typevalidatie, limiet per bestand, opslag in database (BYTEA). - multiple uploads, type validation, per-file size limits, storage in database (BYTEA).
- Delete-strategie: - Delete strategy:
- soft delete als standaard, - soft delete by default,
- permanente delete alleen admin en alleen na soft delete. - permanent delete only for admins and only after soft delete.
## Deployment en operations ## Deployment and Operations
- Stackbestand exposeert: - Stack exposes:
- app op `8080` - app on `8080`
- adminer op `8081` - adminer on `8081`
- Postgres persistent volume: - PostgreSQL persistent volume:
- `/docker/appdata/backupchecks/backupchecks-postgres:/var/lib/postgresql/data` - `/docker/appdata/backupchecks/backupchecks-postgres:/var/lib/postgresql/data`
- In `deploy/backupchecks-stack.yml` staan onderaan ook voorbeeld `.env` variabelen opgenomen. - `deploy/backupchecks-stack.yml` also contains example `.env` variables at the bottom.
## Build/release-flow ## Build/Release Flow
Bestand: `build-and-push.sh` File: `build-and-push.sh`
- Bump opties: - Bump options:
- `1` patch, `2` minor, `3` major, `t` test. - `1` patch, `2` minor, `3` major, `t` test.
- Release-build: - Release build:
- update `version.txt` - update `version.txt`
- commit + tag + push - commit + tag + push
- docker push van `:<version>`, `:dev`, `:latest` - docker push of `:<version>`, `:dev`, `:latest`
- Test-build: - Test build:
- alleen `:dev` - only `:dev`
- geen commit/tag. - no commit/tag.
- Services worden ontdekt onder `containers/*` met Dockerfile-per-service. - Services are discovered under `containers/*` with Dockerfile-per-service.
## Technische observaties / aandachtspunten ## Technical Observations / Attention Points
- `README.md` is momenteel leeg; snelle instapinformatie ontbreekt. - `README.md` is currently empty; quick-start entry context is missing.
- `LICENSE` is momenteel leeg. - `LICENSE` is currently empty.
- `docs/architecture.md` is momenteel leeg. - `docs/architecture.md` is currently empty.
- `deploy/backupchecks-stack.yml` bevat hardcoded voorbeeldwaarden (`Changeme`), risico op foutief gebruik zonder secrets-management. - `deploy/backupchecks-stack.yml` contains hardcoded example values (`Changeme`), with risk if used without proper secrets management.
- App voert DB-init + migraties uit tijdens startup; bij grotere schemawijzigingen kan dit opstarttijd/robustness beïnvloeden. - The app performs DB initialization + migrations at startup; for larger schema changes this can impact startup time/robustness.
- Er is veel functionaliteit rondom parsering en ticketing; regressierisico bij routewijzigingen is hoog zonder gerichte tests. - There is significant parser and ticketing complexity; route changes carry regression risk without targeted testing.
- Voor Autotask update-calls moet `description` expliciet behouden blijven bij updates (voorkomt ongewenste NULL-overschrijving). - For Autotask update calls, the `description` field must be explicitly preserved to prevent unintended NULL overwrite.
- Security-hygiëne blijft belangrijk: - Security hygiene remains important:
- geen klantnamen in parservoorbeelden/broncode, - no customer names in parser examples/source,
- geen hardcoded credentials. - no hardcoded credentials.
## Snelle referenties ## Quick References
- App entrypoint: `containers/backupchecks/src/backend/app/main.py` - App entrypoint: `containers/backupchecks/src/backend/app/main.py`
- App factory: `containers/backupchecks/src/backend/app/__init__.py` - App factory: `containers/backupchecks/src/backend/app/__init__.py`
- Config: `containers/backupchecks/src/backend/app/config.py` - Config: `containers/backupchecks/src/backend/app/config.py`
- Modellen: `containers/backupchecks/src/backend/app/models.py` - Models: `containers/backupchecks/src/backend/app/models.py`
- Parsers: `containers/backupchecks/src/backend/app/parsers/registry.py` - Parsers: `containers/backupchecks/src/backend/app/parsers/registry.py`
- Ticketing utils: `containers/backupchecks/src/backend/app/ticketing_utils.py` - Ticketing utilities: `containers/backupchecks/src/backend/app/ticketing_utils.py`
- Run checks routes: `containers/backupchecks/src/backend/app/main/routes_run_checks.py` - Run Checks routes: `containers/backupchecks/src/backend/app/main/routes_run_checks.py`
- Compose stack: `deploy/backupchecks-stack.yml` - Compose stack: `deploy/backupchecks-stack.yml`
- Build script: `build-and-push.sh` - Build script: `build-and-push.sh`