# ooopeople/facebook_monitor_py architecture

> Architecture diagram of the GitHub repository ooopeople/facebook_monitor_py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ooopeople/facebook_monitor_py
- Repository: https://github.com/ooopeople/facebook_monitor_py

## Overview

1. **System shape**
   This is a local-first desktop application, not a pure web service. The main process starts a FastAPI-based Web UI, coordinates a background scheduler/worker, and uses a dedicated Playwright browser profile to inspect Facebook.

2. **Primary runtime entry points**
   `src/facebook_monitor/__main__.py` and launcher/runtime modules bootstrap the app. They handle instance locking, startup diagnostics, logging, loopback binding, and platform integration such as the Windows tray and frozen-app update handoff.

3. **Web UI boundary**
   `webapp/` is the human-facing control plane. It serves dashboard pages, settings, target management, sidebar layout, scan diagnostics, and partial refreshes via FastAPI routes, templates, static JS/CSS, and presenter/read-model code. It does not own scan logic; it renders state from application and persistence layers.

4. **Application orchestration layer**
   `application/` is the use-case boundary between UI, scheduler, persistence, and runtime. It manages target creation, config merges, target lifecycle and runtime decisions, maintenance, scan recording, update flow, and notification admin actions. This layer is where command-like requests are turned into coordinated changes across subsystems.

5. **Target-scoped architecture**
   The core domain is organized around targets. A target represents either a Facebook group feed or a single post comments thread, with its own config, keyword rules, refresh policy, seen/latest-scan state, match history, runtime state, and notification settings. This target-scoped model is the main unit that flows through UI, worker, and storage.

6. **Facebook interaction subsystem**
   `facebook/` contains all Facebook-specific extraction and navigation logic: route detection, permalink handling, sort/load-more control, feed/comment DOM scripts, text cleanup, and extractor/normalizer pipelines. This layer isolates brittle Facebook DOM behavior from the rest of the app and records diagnostics such as sort adjustments and extraction rounds.

7. **Background scan engine**
   `worker/` runs the actual monitoring workflow. It includes one-shot and resident execution modes, posts/comments pipelines, scan orchestration, commit coordination, finalization, failure handling, recovery, and maintenance eligibility. The worker consumes target state, drives Playwright automation, extracts items, and decides what gets committed.

8. **Browser automation boundary**
   `automation/` encapsulates Playwright browser runtime and profile leasing. The app deliberately uses a dedicated automation profile stored under app data rather than the user’s normal browser profile, which is a major operational and security boundary.

9. **Persistence and state model**
   `persistence/` is a SQLite-backed storage layer with explicit schema/versioning, migrations, repositories, invariants, and schema repair. It stores target configs, runtime state, latest scan items, seen items, dedupe state, match history, notification outbox entries, sidebar layout, scan runs, and app settings. SQLite is the durable source of truth for app state.

10. **Notification delivery boundary**
   `notifications/` separates match detection from external side effects using an outbox pattern. Scans write notification-intent records to SQLite first; a dispatcher later sends via desktop, ntfy, or Discord. This keeps scan transactions reliable and allows failed sends to be retried, cleaned up, or diagnosed without losing evidence.

11. **Diagnostics and supportability**
   `diagnostics/` builds redacted support bundles and collects scan/runtime/database evidence. The repo emphasizes structured diagnostics instead of collapsing failures into a single boolean, which matters for investigating Facebook DOM breakage, notification issues, or persistence anomalies.

12. **Update and release pipeline**
   `updates/` implements signed release discovery, download, validation, staging, and application of updates for frozen builds. Packaging scripts under `packaging/` plus admin scripts generate release artifacts for Windows portable and macOS onedir distributions, while preserving the `data/` directory across updates.

13. **Shared policy and models**
   `core/` holds pure domain policies and common models: keyword matching, dedupe, limits, redaction, notification channel rules, refresh policy, scan failure policy, and user-facing messages. This layer is intentionally framework-agnostic and is reused by application, worker, notifications, and web UI code.

14. **Main data flow to draw**
   A user edits a target in the Web UI → application services validate and persist config → scheduler/worker picks the target up → Playwright automation reads Facebook via DOM scripts → extracted items are normalized and compared against target state → matches are written to SQLite and notification outbox → dispatcher sends external notifications → Web UI refreshes from read models and revision notifications.

15. **Operational boundaries**
   The app is designed to stay local and recoverable: loopback web access by default, CSRF on mutating routes, per-target runtime control, instance locks to prevent duplicate launches, and explicit maintenance/recovery paths for scans and resident workers. These are the boundaries most important for an accurate architecture diagram.

Main entry points: [`src/facebook_monitor/worker`](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/worker) (Worker), [`src/facebook_monitor/launcher.py`](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/launcher.py) (Launcher), [`src/facebook_monitor/persistence`](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/persistence) (SQLite store), [`src/facebook_monitor/application`](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/application) (App services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Main<br/>entrypoint<br/>[__main__.py]"))
  node_launcher["Launcher<br/>startup orchestration<br/>[launcher.py]"]
  node_runtime_core["Runtime core<br/>process services"]
  node_versioning(("Versioning<br/>build metadata<br/>[versioning.py]"))
end

subgraph group_control["Control plane"]
  node_webapp["Web UI<br/>FastAPI control plane"]
end

subgraph group_orchestration["Orchestration"]
  node_app_services["App services<br/>use-case layer"]
  node_target_services["Targets<br/>target coordination"]
  node_update_flow["Update flow<br/>release coordination<br/>[update_flow.py]"]
  node_scheduler["Scheduler<br/>scan planner"]
  node_updater(("Updater<br/>frozen-build helper<br/>[updater.py]"))
end

subgraph group_scan["Scan engine"]
  node_worker["Worker<br/>scan executor"]
  node_facebook["Facebook<br/>DOM extraction"]
  node_automation[("Browser runtime<br/>playwright profile")]
  node_profile["Profile setup<br/>local browser prep<br/>[profile_setup.py]"]
end

subgraph group_state["State"]
  node_persistence[("SQLite store<br/>durable state")]
  node_notification["Notifications<br/>outbox delivery"]
  node_core["Core policy<br/>domain models"]
  node_diagnostics["Diagnostics<br/>support bundle"]
end

node_main -->|"boot"| node_launcher
node_launcher -->|"init"| node_runtime_core
node_launcher -->|"serve"| node_webapp
node_launcher -->|"start"| node_scheduler
node_launcher -->|"handoff"| node_updater
node_versioning -.->|"metadata"| node_launcher
node_webapp -->|"commands"| node_app_services
node_webapp -->|"read models"| node_persistence
node_webapp -.->|"policy"| node_core
node_app_services -->|"targets"| node_target_services
node_app_services -->|"admin"| node_notification
node_app_services -->|"updates"| node_update_flow
node_app_services -.->|"support"| node_diagnostics
node_scheduler -->|"dispatch"| node_worker
node_scheduler -->|"state"| node_persistence
node_worker -->|"drive"| node_automation
node_worker -->|"extract"| node_facebook
node_worker -->|"commit"| node_persistence
node_worker -->|"enqueue"| node_notification
node_worker -.->|"decide"| node_core
node_facebook -.->|"dom"| node_automation
node_profile -->|"prepare"| node_automation
node_notification -->|"outbox"| node_persistence
node_diagnostics -.->|"collect"| node_persistence
node_updater -.->|"handoff state"| node_persistence

click node_main "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/__main__.py"
click node_launcher "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/launcher.py"
click node_runtime_core "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/runtime"
click node_webapp "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/webapp"
click node_app_services "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/application"
click node_target_services "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/application/target_create_service.py"
click node_update_flow "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/application/update_flow.py"
click node_scheduler "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/scheduler"
click node_worker "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/worker"
click node_facebook "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/facebook"
click node_automation "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/automation"
click node_persistence "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/persistence"
click node_notification "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/notifications"
click node_core "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/core"
click node_diagnostics "https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/diagnostics"
click node_profile "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/profile_setup.py"
click node_updater "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/updater.py"
click node_versioning "https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/versioning.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_launcher,node_runtime_core,node_versioning toneBlue
class node_webapp toneAmber
class node_app_services,node_target_services,node_update_flow,node_scheduler,node_updater toneMint
class node_worker,node_facebook,node_automation,node_profile toneRose
class node_persistence,node_notification,node_core,node_diagnostics toneIndigo
```

## Components

### Runtime

Process startup, locks, logging, tray, and update handoff.

- [Main](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/__main__.py): entrypoint · CLI bootstrap and process startup. · `src/facebook_monitor/__main__.py`
- [Launcher](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/launcher.py): startup orchestration · Launches the app, manages instance lock, ports, and platform handoff. · `src/facebook_monitor/launcher.py`
- [Runtime core](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/runtime): process services · Logging, paths, CSRF, build metadata, tray, and startup diagnostics. · `src/facebook_monitor/runtime`
- [Versioning](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/versioning.py): build metadata · Version and release identity helpers used by startup and updates. · `src/facebook_monitor/versioning.py`

### Control plane

Human-facing FastAPI web app and UI read models.

- [Web UI](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/webapp): FastAPI control plane · Dashboard, settings, targets, partial refreshes, and static assets. · `src/facebook_monitor/webapp`

### Orchestration

Application services that coordinate targets, scans, and updates.

- [App services](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/application): use-case layer · Target lifecycle, maintenance, scan recording, notifications, and update actions. · `src/facebook_monitor/application`
- [Targets](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/application/target_create_service.py): target coordination · Target creation, config merge, registry, runtime decisions, and lifecycle management. · `src/facebook_monitor/application/target_create_service.py`
- [Update flow](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/application/update_flow.py): release coordination · Discovery, validation, staging, and frozen-build update handoff. · `src/facebook_monitor/application/update_flow.py`
- [Scheduler](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/scheduler): scan planner · One-shot planning, loop control, and runtime recovery triggers. · `src/facebook_monitor/scheduler`
- [Updater](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/updater.py): frozen-build helper · Release handoff and update execution entrypoint. · `src/facebook_monitor/updater.py`

### Scan engine

Worker, Facebook extraction, and browser automation.

- [Worker](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/worker): scan executor · Resident and one-shot scan execution, commit coordination, and recovery. · `src/facebook_monitor/worker`
- [Facebook](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/facebook): DOM extraction · Route detection, permalink handling, sort control, text cleanup, and extractors. · `src/facebook_monitor/facebook`
- [Browser runtime](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/automation): playwright profile · Dedicated Playwright browser runtime and leased automation profile. · `src/facebook_monitor/automation`
- [Profile setup](https://github.com/ooopeople/facebook_monitor_py/blob/main/src/facebook_monitor/profile_setup.py): local browser prep · Login and profile preparation for the dedicated browser profile. · `src/facebook_monitor/profile_setup.py`

### State

Persistence, domain models, notifications, and diagnostics.

- [SQLite store](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/persistence): durable state · Schema, migrations, repositories, invariants, and repair over app state. · `src/facebook_monitor/persistence`
- [Notifications](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/notifications): outbox delivery · Match and failure outbox, channel dispatch, and retryable delivery. · `src/facebook_monitor/notifications`
- [Core policy](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/core): domain models · Pure matching, dedupe, limits, refresh policy, redaction, and messages. · `src/facebook_monitor/core`
- [Diagnostics](https://github.com/ooopeople/facebook_monitor_py/tree/main/src/facebook_monitor/diagnostics): support bundle · Redacted runtime, scan, target, notification, and database evidence collection. · `src/facebook_monitor/diagnostics`

## Connections

- Main → Launcher: boot · Starts the application and delegates runtime setup.
- Launcher → Runtime core: init · Configures logging, paths, locks, diagnostics, and platform integration.
- Launcher → Web UI: serve · Starts the loopback FastAPI UI.
- Launcher → Scheduler: start · Begins scheduling or resident execution.
- Launcher → Updater: handoff · Transfers frozen builds into update flow when needed.
- Versioning → Launcher: metadata · Provides build and version identity used during startup.
- Web UI → App services: commands · UI routes invoke application use cases.
- Web UI → SQLite store: read models · Renders dashboard and settings state from SQLite-backed projections.
- Web UI → Core policy: policy · Uses shared models, limits, and presentation rules.
- App services → Targets: targets · Creates, updates, and coordinates target-scoped behavior.
- App services → Notifications: admin · Manages notification setup, tests, and dispatch-related actions.
- App services → Update flow: updates · Coordinates release check, staging, and application flow.
- App services → Diagnostics: support · Collects evidence for maintenance and troubleshooting.
- Scheduler → Worker: dispatch · Hands target work to the scan engine.
- Scheduler → SQLite store: state · Reads target/runtime state and recovery signals.
- Worker → Browser runtime: drive · Uses Playwright runtime and leased browser profile.
- Worker → Facebook: extract · Runs Facebook-specific navigation and DOM extraction.
- Worker → SQLite store: commit · Writes scan results, seen state, and runtime outcomes.
- Worker → Notifications: enqueue · Writes match and failure intents to the notification outbox.
- Worker → Core policy: decide · Applies dedupe, limits, refresh, and failure policies.
- Facebook → Browser runtime: dom · Depends on browser session and page controls.
- Profile setup → Browser runtime: prepare · Sets up the dedicated browser profile used by automation.
- Notifications → SQLite store: outbox · Uses SQLite as the durable queue and dedupe source of truth.
- Diagnostics → SQLite store: collect · Reads database evidence for support bundles.
- Updater → SQLite store: handoff state · Persists pending update state and cleanup markers.