ivooskamp/backupchecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d2cdd34541
backupchecks/docs/technical-notes-codex.md

7.1 KiB
Raw Blame History

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