Документация

Architecture Overview

Crisis-Monitor is a Flask application that combines a traditional web interface with asynchronous background jobs and scheduled maintenance tasks. The project structure described below mirrors the layout outlined in the README so engineers and operators can cross-reference both documents without encountering conflicts.

High-level layout

  • Web application: Flask blueprints serve the authenticated HTML interface, JSON APIs and background admin tools. Templates live in templates/, static assets in static/.
  • Database layer: SQLAlchemy models inside app.models map the relational schema. Alembic migrations managed by Flask-Migrate live in migrations/.
  • Background services: ARQ cron jobs (defined in services/worker.py) handle periodic tasks. In production the same functions can also be triggered via system cron using CLI commands from cli.py (see crontab.example).
  • Auxiliary scripts: Command-line entry points such as run.py, backup.py, import_tickets.py and utilities under utils/ provide repeatable operational workflows.

Web blueprints

Blueprint registration happens in app/blueprints.py and mirrors the breakdown below.

Foundation and account management

  • auth – authentication, session handling and administration of user accounts.
  • localization – switch the interface language and persist the chosen locale.
  • help – serve Markdown help articles for the in-app help drawer.
  • whats_new – deliver release notes to signed-in users.
  • templates – manage reusable ticket templates and auto-fill payloads.
  • teams – CRUD views for user teams and bundled permissions.

Ticket lifecycle and collaboration

  • tickets – the main incident interface (list, create, edit, filters and API endpoints). Auxiliary modules such as tickets.notes, tickets.attachments, tickets.favorites, tickets.checklist, tickets.import, tickets.bulk and tickets.export extend the core workflow.
  • buffer – temporarily store URLs and snippets before they become draft incidents.
  • shift_log – capture handover notes between shifts.

Analytics and situational awareness

  • tickets_dashboard – KPI dashboards, admin-only system health views and exportable reports under /dashboard and /admin/status.
  • live_dashboard – lightweight live metrics at /dashboard/live powered by server-sent events.
  • postmortem – incident comparisons and timeline reviews.
  • reports – build asynchronous PDF and data exports under /reports.
  • cop – the “common operating picture” dashboard for executives.
  • aar – after-action review workflows and follow-up tracking.

Communications and knowledge management

  • communications – manage communication templates, audiences and delivery channels for outbound messaging.
  • info_plan – maintain information response plans per incident.
  • audience – administer target audiences and cultural checklists.
  • notifications – per-user alert preferences plus admin management screens.
  • narratives – curate counter-narrative content, media assets and categories.
  • disinformation – track disinformation cases and rebuttal workflows.

Administration and monitoring

  • admin – manage users, roles, escalation rules and cached configuration.
  • backups – create, download and restore database backups via /admin/backups.
  • search – provide the global search endpoint used throughout the interface.
  • scripts – expose Flask CLI commands for seeding, maintenance and data import.
  • Prometheus metrics are exposed via utils.monitoring and the custom MonitoringScheduler, which is initialised in create_app.

Benchmark-derived v1 contracts

The current expansion work is intentionally split into small contracts with explicit ownership and non-goals. The implementation notes below are the canonical references for those boundaries:

  • Source registry – known collection paths and ownership metadata.
  • Feed health – persisted probe outcomes separate from event freshness.
  • Source credibility – descriptive review composition without invented ratings.
  • Team activation – read-only staffing and workload visibility until acknowledgement writes have an approved audit contract.
  • Narrative velocity – observed two-window signal without clustering or attribution claims.
  • Forecast registry – scenario bands, outcome states and explicit calibration boundaries.
  • Field report – online-first observation workflow; offline retry and background sync are separate work.
  • Evidence bundle – privacy-safe AAR learning summary for machine and audit consumers.
  • Claim decomposition – linked disinformation signals presented as observed claims with an explicit review and privacy boundary.
  • Analytics evidence context – source, window, sample size and period-preserving drilldown for the overview.
  • Operator readiness scorecard – weighted current-shift exceptions and coverage with explicit empty-sample behavior.

The 2026-08-04 benchmark release audit contains the corresponding runtime and browser evidence. It also records the very-wide AV DS 4 composition pass separately from these data contracts.

Data model and relationships

Core entities such as User, CrisisTicket, TicketAttachment and supporting reference tables live in app.models. SQLAlchemy relationships express how incidents connect to regions, emergency types, statuses and notes. Migrations created with Flask-Migrate ensure schema changes remain reproducible.

classDiagram
    class User
    class Role
    class CrisisTicket
    class TicketAttachment
    class TicketNote
    class Region
    class EmergencyType
    class Status
    User --> Role
    User "1" --> "*" CrisisTicket
    CrisisTicket --> TicketAttachment
    CrisisTicket --> TicketNote
    CrisisTicket --> Region
    CrisisTicket --> EmergencyType
    CrisisTicket --> Status
    User --> TicketNote

Technology stack

The README lists the exact dependency versions. The most significant components are Flask 3.1, SQLAlchemy 2.0, Flask-SQLAlchemy, Flask-Login, Flask-Migrate, Flask-WTF, Flask-Babel, ARQ, Prometheus-Flask-Exporter and the Material for MkDocs documentation theme. The frontend uses Vite with npm-managed packages.

Background tasks and schedulers

ARQ cron jobs defined in services/worker.py handle all periodic work:

  • create compressed backups in BACKUP_DIR,
  • delete old log and temporary files using utils.cleanup_utils,
  • archive resolved tickets, flush ticket metrics and expire undo actions,
  • perform periodic health checks through MonitoringScheduler,
  • ingest external data feeds (GDELT, ReliefWeb, GDACS),
  • run escalation rules and stale-ticket auto-escalation.

In production the same functions can be invoked via system cron using the CLI commands in cli.py. See crontab.example for a ready-to-use schedule.

python run.py accepts flags such as --reset, --seed, --host and --port that simplify local development and scripted maintenance tasks.

Monitoring stack

make monitor-up starts Prometheus, Grafana and Alertmanager for local testing. The Flask application exposes metrics via Prometheus-Flask-Exporter so Grafana can visualise incident throughput, background job latency and system health. Use make monitor-down to stop the containers.

Help links

app/help.py maps template names to documentation anchors via HELP_LINKS. Add new entries to expose context-sensitive help inside the UI:

HELP_LINKS['report_form'] = 'overview#reports'

When report_form.html renders, the floating help button links to /help/overview.md#reports.