backupchecks/docs/technical-notes-codex.md

Technical Notes (Internal)

Last updated: 2026-02-13

Purpose

Internal technical snapshot of the backupchecks repository for faster onboarding, troubleshooting, and change impact analysis.

Repository Overview

• Application: Flask web app with SQLAlchemy and Flask-Migrate.
• Runtime: Containerized (Docker), deployed via Docker Compose stack.
• Primary source code location: containers/backupchecks/src.
• The project also contains extensive functional documentation in docs/ and multiple roadmap TODO files at repository root.

Main Structure

• containers/backupchecks/Dockerfile: Python 3.12-slim image, starts gunicorn with backend.app:create_app().
• containers/backupchecks/requirements.txt: Flask stack + PostgreSQL driver + reporting libraries (reportlab, Markdown).
• containers/backupchecks/src/backend/app: backend domain logic, routes, parsers, models, migrations.
• containers/backupchecks/src/templates: Jinja templates for auth/main/documentation pages.
• containers/backupchecks/src/static: CSS, images, favicon.
• deploy/backupchecks-stack.yml: compose stack with backupchecks, postgres, adminer.
• build-and-push.sh: release/test build script with version bumping, tags, and image push.
• docs/: functional design, changelogs, migration notes, API notes.

Application Architecture (Current Observation)

• Factory pattern: create_app() in containers/backupchecks/src/backend/app/__init__.py.
• Blueprints:
  • auth_bp for authentication.
  • main_bp for core functionality.
  • doc_bp for internal documentation pages.
• Database initialization at startup:
  • db.create_all()
  • run_migrations()
• Background task:
  • start_auto_importer(app) starts the automatic mail importer thread.
• Health endpoint:
  • GET /health returns { "status": "ok" }.

Functional Processing Flow

• Import:
  • Email is fetched via Microsoft Graph API.
• Parse:
  • Parser selection through registry + software-specific parser implementations.
• Approve:
  • New jobs first appear in Inbox for initial customer assignment.
• Auto-process:
  • Subsequent emails for known jobs automatically create JobRun records.
• Monitor:
  • Runs appear in Daily Jobs and Run Checks.
• Review:
  • Manual review removes items from the unreviewed operational queue.

Configuration and Runtime

• Config is built from environment variables in containers/backupchecks/src/backend/app/config.py.
• Important variables:
  • APP_SECRET_KEY
  • APP_ENV
  • APP_PORT
  • POSTGRES_DB
  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • DB_HOST
  • DB_PORT
• Database URI pattern:
  • postgresql+psycopg2://<user>:<pass>@<host>:<port>/<db>
• Default timezone in config: Europe/Amsterdam.

Data Model (High-level)

File: containers/backupchecks/src/backend/app/models.py

• Auth/users:
  • User with role(s), active role in session.
• System settings:
  • SystemSettings with Graph/mail settings, import settings, UI timezone, dashboard policy, sandbox flag.
  • Autotask configuration and cache fields are present.
• Logging:
  • AuditLog (legacy alias AdminLog).
• Domain:
  • Customer, Job, Override, plus extensive run/ticket logic in other modules/routes.
  • Core entities from system knowledge include JobRun, MailMessage, ticket/remark link tables, and feedback tables.

Parser Architecture

• Folder: containers/backupchecks/src/backend/app/parsers/
• Two layers:
  • registry.py:
    • matching/documentation/visibility on /parsers.
    • examples must stay generic (no customer names).
  • parser files (veeam.py, synology.py, etc.):
    • actual detection and parsing logic.
    • return structured output: software, type, job name, status, objects.
• Practical rule:
  • extend patterns by adding, not replacing (backward compatibility).

Ticketing and Autotask (Critical Rules)

• Two ticket tracks:
  • internal tickets (tickets, ticket_scopes, ticket_job_runs).
  • Autotask ticket fields on job_runs + synchronization with internal ticket records.
• Propagation to new runs is handled by link_open_internal_tickets_to_run.
• This propagation must be called for:
  • email-based run creation (import flow),
  • missed-run generation in routes_run_checks.py.
• Display logic:
  • link-based via explicit JOIN queries.
  • resolved tickets (resolved_at set) must no longer be linked to new runs.
  • historical links remain visible for audit trail.
• Anti-patterns (do not use):
  • date-based resolved logic like resolved_at >= run_date.

UI and UX Notes

• Navbar is fixed-top with dynamic main container padding correction.
• Status badges use semantic color coding (success/warning/error/override/reviewed).
• Ticket copy button uses a three-level fallback:
  • Clipboard API,
  • execCommand('copy'),
  • prompt() fallback.

Feedback Module with Screenshots

• Models: FeedbackItem, FeedbackVote, FeedbackReply, FeedbackAttachment.
• Attachments:
  • multiple uploads, type validation, per-file size limits, storage in database (BYTEA).
• Delete strategy:
  • soft delete by default,
  • permanent delete only for admins and only after soft delete.

Deployment and Operations

• Stack exposes:
  • app on 8080
  • adminer on 8081
• PostgreSQL persistent volume:
  • /docker/appdata/backupchecks/backupchecks-postgres:/var/lib/postgresql/data
• deploy/backupchecks-stack.yml also contains example .env variables at the bottom.

Build/Release Flow

File: build-and-push.sh

• Bump options:
  • 1 patch, 2 minor, 3 major, t test.
• Release build:
  • update version.txt
  • commit + tag + push
  • docker push of :<version>, :dev, :latest
• Test build:
  • only :dev
  • no commit/tag.
• Services are discovered under containers/* with Dockerfile-per-service.

Technical Observations / Attention Points

• README.md is currently empty; quick-start entry context is missing.
• LICENSE is currently empty.
• docs/architecture.md is currently empty.
• deploy/backupchecks-stack.yml contains hardcoded example values (Changeme), with risk if used without proper secrets management.
• The app performs DB initialization + migrations at startup; for larger schema changes this can impact startup time/robustness.
• There is significant parser and ticketing complexity; route changes carry regression risk without targeted testing.
• For Autotask update calls, the description field must be explicitly preserved to prevent unintended NULL overwrite.
• Security hygiene remains important:
  • no customer names in parser examples/source,
  • no hardcoded credentials.

Quick References

• 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
• Models: containers/backupchecks/src/backend/app/models.py
• Parsers: containers/backupchecks/src/backend/app/parsers/registry.py
• Ticketing utilities: 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
• Build script: build-and-push.sh