ooopeople/facebook_monitor_py

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.