MajoorWaldi-ComfyUI-Majoor-AssetsManager/docs/ARCHITECTURE_MAP.md

Architecture Map

Version: 2.4.5
Last Updated: April 10, 2026

This map is the working reference for backend refactors. It is intentionally short and operational.

Package Responsibilities

• mjr_am_backend/routes
  • HTTP surface only.
  • Parse request data, apply auth/CSRF/rate-limit guards, call services, map Result payloads.
  • route_catalog.py — declarative route registry (RouteRegistration dataclass, CORE + OPTIONAL catalogs).
• mjr_am_backend/routes/core
  • Shared route helpers for security, path rules, JSON parsing, responses, and service resolution.
• mjr_am_backend/routes/assets
  • Thin compatibility facades re-exporting from features/assets/.
• mjr_am_backend/features
  • Business logic and orchestration by domain: index, metadata, collections, browser, health, tags, viewer.
• mjr_am_backend/features/assets
  • Asset domain sub-services:
    • lookup_service — asset lookups and queries
    • download_service — download/streaming logic
    • rating_tags_service — ratings, tags, collections
    • request_context_service — request parsing and context extraction
    • path_resolution_service — root/subfolder/path resolution
    • delete_service — asset deletion
    • rename_service — asset renaming
    • filename_validator — filename validation rules
    • models — shared data models
    • service — thin compatibility facade
• mjr_am_backend/adapters
  • Boundary code for SQLite, filesystem watchers, external tools, and other integration points.
• mjr_am_backend/adapters/db
  • sqlite_facade.py — main entry point for DB access (~1900 L)
  • sqlite_connections.py — connection pool, pragmas, acquire/release
  • sqlite_execution.py — query execution, timeout, retry, batch
  • sqlite_lifecycle.py — transactions, reset, WAL, Windows file-handle management
  • sqlite_recovery.py — malformed recovery, FTS rebuild, schema repair
  • schema.py (331 L) + schema_sql.py, schema_fts.py, schema_vec.py — DDL and migration
  • connection_pool.py, db_recovery.py, transaction_manager.py — lower-level helpers
• mjr_am_shared
  • Shared result types, error definitions, logging, time helpers, and cross-cutting utilities.

Frontend

• Vue 3 + Pinia for all major UI surfaces (grid, sidebar, feed, context menus, settings).
• js/vue/ — Vue components and stores.
• js/features/ — feature-scoped JS modules.
• js/stores/ — Pinia stores.
• Imperative runtime services remain for viewer, DnD, and ComfyUI integration (by design).

Request Flow

UI action -> route handler -> route/core helper -> feature service -> adapter -> DB/filesystem/tool -> Result response -> UI mapping

Rules:

• Routes do not decide filesystem or security policy locally.
• Services own business rules and orchestration.
• Adapters isolate external side effects.
• security.py is the single policy entry point for auth, write access, safe mode, trusted proxies, and CSRF.

Watcher And Index Flow

Filesystem event -> watcher scope/runtime -> index orchestration -> DB update -> UI refresh event

Hot zones:

• watcher lifecycle and scope resolution
• reset/rebuild orchestration
• metadata probing and vector backfill
• live viewer synchronization

These zones should be refactored behind stable service facades before adding new behavior.

Security Rules

• Public API base stays /mjr/am/*.
• Backend returns structured Result payloads for expected errors.
• Safe mode is enabled by default.
• Remote write remains denied without a valid token.
• Loopback write is allowed by default in the current compatibility model unless MAJOOR_REQUIRE_AUTH=1 is set.

Naming And Internal API Conventions

• Public internal APIs should be thin, stable facades under features/* or routes/core/*.
• Route modules may import facades and helpers, but should not directly orchestrate storage internals across multiple subsystems.
• New security-sensitive mutations must call shared security and path helpers instead of duplicating checks.