Development and Architecture

Development and Architecture

Architecture Overview

The project is split into a Python backend and a JavaScript frontend.

Main repository areas:

• mjr_am_backend/ for routes, adapters, features, and service logic
• mjr_am_shared/ for shared primitives such as logging, errors, and results
• js/ for frontend application code and UI components
• tests/ for backend tests and integration coverage

Backend Design Notes

The backend uses asynchronous aiohttp handlers, SQLite-based persistence, and a Result-oriented error handling pattern.

Frontend Design Notes

The frontend handles grid browsing, viewer workflows, interaction surfaces, and feature-specific UI behavior.

Quality Gates

Recommended validation commands are maintained in the repository docs, including pytest, frontend tests, linting, and complexity checks.

Plugin Architecture

The repository now includes a documented plugin-system track for metadata extractors. That work is important enough to treat as a first-class architecture area rather than a footnote.

The plugin docs cover:

• discovery and validation
• runtime registry and lifecycle management
• security constraints for third-party extractor code
• example extractors and integration flow

Canonical Docs

• Architecture Map
• API Reference
• Testing Guide
• ADR Index
• Plugin System Design
• Plugin Implementation Summary