AMMSTRO AMMS — Wiki Portal

Project Summary

AMMS v2 (Aircraft Maintenance Management System) is a full-stack CAMO/MRO platform for managing the continuing airworthiness of an aircraft fleet — built Malaysia-first around real regulatory practice. It ingests an aircraft's complete maintenance history, tracks what is due, plans and executes work packages, and closes them through technical-records review, with multi-tenant isolation and role-based access control.

Stack: Python 3 + FastAPI + SQLite (event-driven engine architecture, ~23k-line main.py) · vanilla-JS frontend served as static files by the same uvicorn process (port 8000) · Google Gemini AI assist for AMP extraction and TSF draft assistants · pytest + E2E suites · manual deployment via deploy.sh / systemd (/opt/amms).

One web server serves everything: JSON API under /api/v1/*, frontend mounted at /.

Modules Summary

Frontend modules (sidebar)

Dashboard

Fleet overview, compliance summary widgets.

Fleet

Aircraft list and detail tabs: utilization (FH/FC counters), LDND due status, configuration, components (LLP/HTC/OCCM), structural damage, compliance register, baseline reconciliation.

Phase-In

8-stage onboarding (CH-01…CH-08): identity & baseline, bulk CSV/PDF ingestion, sandbox review & correction, normalization, reconciliation, validation, commitment, activation.

Engineering

AMP import/revisions/block checks, technical publications (TP), publication evaluations (PE), engineering orders (EO), task card management, structural damage cases.

Planning

Forecast timeline & smart forecast, OOP planning pool, draft work packages, scope editing, calendar view, BOW packs for MRO handover.

Operations (MOC/PPC)

AJL intake & review, LMR tier-1/operational checks, DDL registry & lifecycle, grounding, dispatch readiness, production control queues, request orders.

Maintenance

Execution boards, task orders & action steps, findings → NRC routing, DFP evidence, OOP review, records packs.

Library

Unified document service: uploads, revisions, archive, related-publication relationships.

Administration / System-wide

User management (RBAC), tenant scope, audit trail, AJL configuration workspace.

Backend engines (each owns its tables, coordinated via event bus)

Engine	File	Responsibility
Phase-In	phase_in_engine.py	CH-01→CH-08 aircraft onboarding pipeline, staged ingestion, sandbox corrections
Utilization	util_engine.py	Flight logs, FH/FC counters, counter ledger (ENG-01)
Rules	rules_engine.py	Task/directive definitions, compliance logic (ENG-02)
LDND	ldnd_engine.py	Last Done / Next Due computation, unified due views (ENG-03)
Configuration	cfg_engine.py	Components, assemblies, capability inference (ENG-04)
Structural	structural_engine.py	Damage cases, repeat inspections (ENG-05)
Work Package v2	workpackage_v2_*.py (~30 files)	Full WP lifecycle: draft→closure, task orders, injection, findings, evidence, OIL gates, BOW packs, reschedule/withdrawal (ENG-06)
Airworthiness (AEE)	airworthiness_engine.py	Grounding, MEL/DDL compliance, aircraft status (ENG-07)
Forecast	forecast_engine.py	Due-date projection, utilization profiles, smart forecast (ENG-08)
Notification	notification_engine.py	Persistent alerts and acknowledgment (ENG-09)
Reconciliation	reconciliation_engine.py	Baseline reconciliation workbench (ENG-10)
MOC	moc_engine.py	AJL queue, DDL registry, dispatch readiness, weekly LMR board
TechPub	techpub_engine.py	TP / PE / EO lifecycle, applicability, supersession, approval chains
Task Card	task_card_engine.py	Manufacturer task card ingestion, requirements & resources, WP inheritance
AMP Extraction	amp_extraction_engine.py	CSV/flat-CSV AMP import with Gemini-assisted repair
Library	library_engine.py	Unified document library service
User Mgmt / Audit	user_management_engine.py, audit_engine.py	RBAC, immutable audit trail (ENG-00)

Work Package Lifecycle core workflow

DRAFT → SUBMITTED → READY → ON_GOING → COMPLETED → UNDER_TECH_REVIEW → CLOSED (Planning) (PPC) (PPC) (Line Maint.) (PPC) (Tech Records)

Supporting flows: task orders & injection, findings → NRC routing, evidence REQUIRED → PROVIDED → VERIFIED, OIL closure gates, records packs, BOW handover packs, readiness conflicts, reschedule & item withdrawal.

Abbreviations

Abbr.	Meaning	Category
AMMS	Aircraft Maintenance Management System	Product
AMMSTRO	Product/brand name of the maintenance suite	Product
CAMO	Continuing Airworthiness Management Organisation	Organisation
MRO	Maintenance, Repair and Overhaul (organisation)	Organisation
PRD	Product Requirements Document (chapters CH-01…CH-3x)	Docs
ADR	Architecture Decision Record	Docs
CH-xx	PRD chapter number (e.g. CH-27 flight log commit contract)	Docs
AD	Airworthiness Directive	Compliance
SB	Service Bulletin	Compliance
EO	Engineering Order	Compliance
TP	Technical Publication	Compliance
PE	Publication Evaluation	Compliance
TSF	Technical Services Form (TSF-001 evaluation, TSF-003 draft assistant)	Compliance
AMP	Aircraft Maintenance Programme	Compliance
MPD	Maintenance Planning Document	Compliance
LDND	Last Done / Next Due (compliance due-status calculation)	Compliance
AEE	Airworthiness Evaluation Engine	Compliance
AOG	Aircraft On Ground	Compliance
MEL	Minimum Equipment List	Compliance
CDL	Configuration Deviation List	Compliance
DDG	Dispatch Deviation Guide	Compliance
DDL	Deferred Defect List	Compliance
RI	Repeat Inspection (structural damage follow-up)	Compliance
MOC	Maintenance Operations Control	Operations
AJL	Aircraft Journey Log	Operations
LMR	Line Maintenance Release / Report (tier-1 daily checks)	Operations
BMR	Base Maintenance Release / Report	Operations
WP	Work Package	Operations
PPC	Production Planning & Control	Operations
OOP	Out-Of-Phase (tasks outside block-check cadence; planning pool)	Operations
OIL	Open Item List (must clear before WP closure)	Operations
NRC	Non-Routine Card (finding raised during execution)	Operations
DFP	Dirty Finger Print (stamped/executed task card evidence)	Operations
BOW	Bill of Work (printable MRO handover pack)	Operations
RO	Request Order (generated from WP bills)	Operations
AMGS	Aircraft Maintenance Ground Schedule	Operations
FH / FC	Flight Hours / Flight Cycles	Utilization
APU	Auxiliary Power Unit	Utilization
MSN	Manufacturer Serial Number	Utilization
LLP	Life-Limited Part	Components
HTC	Hard-Time Component	Components
OCCM	On-Condition / Condition-Monitored component class	Components
CFG	Configuration (aircraft configuration engine)	Components
TSE	Technical Services Engineer (TSE-AMP, TSE-Directive, TSE-Structures)	Roles
STSE	Senior Technical Services Engineer (override/approval authority)	Roles
TRO / TRE	Technical Records Officer / Technical Records Engineer	Roles
MP	Maintenance Planner	Roles
ASP	Aircraft Schedule Planning	Roles
CAMO-HEAD	Head of the CAMO organisation (final authority)	Roles
SYSADMIN	System administrator	Roles
RBAC	Role-Based Access Control	Roles
E2E	End-to-End (testing)	Technical
RAG	Retrieval-Augmented Generation (TSF-001 AI drafts)	Technical
UTC	Coordinated Universal Time (all DB timestamps)	Technical
CORS	Cross-Origin Resource Sharing	Technical
EVT_*	Canonical event-bus event names (e.g. EVT_WORKPACKAGE_TRANSITIONED)	Technical
ENG-xx	Engine catalogue id in the PRD (ENG-00 audit … ENG-10 reconciliation)	Technical

Version History

No formal versions yet: 0 git tags, 0 GitHub releases, 0 deployments, no CI/CD. "v1" = the earlier AMMS demo used as workflow reference; "v2" = this system. The timeline below is the de-facto version history.

Phase	Period	Commits	Theme
1. Foundation	Mar 8–17	~19	FastAPI backend + all 9 module frontends with mock data; v1 workflow alignment.
2. Backend wiring	Mar 18–31	~55	Frontend wired to real APIs; login + global RBAC; E2E tests; Phase-In staged ingestion & sandbox hardening.
3. AMP & AJL-MOC	April	~186	AMP CSV/PDF import + Gemini repair → flat-CSV; block checks; compliance lineage overhaul; TP-PE-EO workflow v1; full AJL-MOC module (journey logs, LMR checks, DDL lifecycle, configurable intake).
4. Work Package v2	May	~158	WP v2 rebuild (schema→closure, ~26 commits); PPC intake; check history; component, task card & structural damage management modules; forecast timeline.
5. Ops checks & library	June	~86	AJL LMR operational checks → LDND writeback; task injection; library rebuild; PE applicability evidence workflow; persisted RAG drafts; async Boeing task card imports.
6. BOW, multi-tenancy & LMR release	Jul 1–15	~85	Task card requirements/resources; WP bills → request orders; BOW print packs; multi-tenant rollout (RBAC role bindings, org-aware login, platform owner console, first-admin onboarding, tenant-scope binding across AMP/PE-EO/techpub/MOC/inventory/audit, then a wave of tenant-scoping bug fixes); LMR release workflow (readiness read model/preview, execution scope history, immutable release snapshot, release action, browser print preview); Inventory/Materials/Tools module (physical tracking foundation, CSV import staging → review/approval → promotion, stock & tool-store read models, material/tool request reservations).
7. Report Centre, AMP Task Control & Weekly authority	Jul 15–31	~55	Report Centre / Report Builder V1 (builder registry, private/shared definitions, preview + sorting/pagination, CSV & XLSX export via openpyxl, compliance-forecast/audit-exception/curated-planning datasets); inventory operational workflows (material issue, tool checkout/return/inspection, receiving, location management, import fixes); AMP Task Control (profile, baseline protection, review backend/UI, presentation, migration sweep) and AMP Task Lineage (matching → shadow → runtime adoption, dangerous-fallback removal); Weekly / operational-check / event authority (op-check policy & cadence, dual-mode occurrence control, event-trigger activation, Weekly route authority, AMP OOP activation & bundling).
8. AJL/MOC workspace restructure	Aug 1–2	~27	A single change-controlled project executed as nine approved slices: the combined Operations → AJL/MOC page is decomposed into routed work areas (guided 5-step AJL workflow · Findings & DDL · Checks & LMR · Templates & Profiles · History & Audit), with Accept AJL confined to Step 5, readiness/capabilities served as authoritative backend projections, tenant & role-forgery hardening, and a shared overlay accessibility/responsive layer. Slice 7 skipped by approval; Slice 9 blocked for browser acceptance — the restructure is not yet declared complete.

Latest Changes updated daily by the monitor

2026-08-06 — 27 new commits: AJL/MOC workspace restructure, delivered slice-by-slice (Aug 1–2)

What this is: a single, tightly change-controlled project that breaks the one giant Operations → AJL/MOC page apart into separate work areas. The stated goal is to make two questions answerable at a glance — what needs MOC attention now? and what must be finished before this AJL can be accepted? Design baseline docs/plans/ajl-moc-workspace-restructure.md plus an append-only evidence log (2414bb8). No SPA framework, no new lifecycle authority — the existing vanilla-JS controller pattern and FastAPI backend are reused throughout.
Slice 1 — navigation & presentation separation (6c08a86, 4a522ab): the combined _buildMocPage() is decomposed into routed work areas with deep-linkable state (work area, selected AJL, step, filters).
Slice 2 — guided AJL workflow shell (60650be, d6dd0f2, f2a0aa7): a focused five-step workspace with persistent aircraft/AJL/template/status/step/blocker context; Accept AJL now exists only in Step 5 (certification) — verified by an audit asserting exactly one acceptance control in the whole frontend.
Slice 3 — authoritative readiness, capabilities, roles & tenant hardening (24cede0, abeb2c8, 36e8352): readiness and permitted actions become backend projections instead of frontend-derived state; the old visual MOC/MOC-Supervisor mode switch stops being treated as authorization. Forged query/body role values grant nothing and cross-tenant reads stay hidden.
Slice 4 — findings & DDL workspace (e667d54, 5a35346, 51d4e9f): findings capture and DDL review/decisions split out of the main flow into their own area (no automatic text-based finding→DDL conversion).
Slice 5 — checks & LMR workload (cee5b2b, 6bbdce9, 6db754c): tier-1/operational checks and the Weekly LMR due board become a dedicated workload area.
Slice 6 — templates & profiles configuration workspace (7923c96, 00fedbd, 451832a, f931af3): AJL configuration coverage, counter profiles, template blocks, source mappings and validation preview move into an admin workspace with a clarified activation-confirmation step (recovered and re-verified after a crash mid-slice).
Slice 7 — skipped by explicit approval (80feab5, 482a5ca, 788cb4e): the optional backend extensions were deliberately not built; existing backend authority was judged sufficient.
Slice 8 — history, diagnostics & audit consolidation (05d4b35, d2b7149, d3d79f0): writeback diagnostics, correction queues and audit information move to a History & Audit area — ordinary MOC users see the record history, AUDITOR additionally receives bounded read-only processing detail.
Slice 9 — accessibility & responsive verification, blocked (a2a8d5e, e3fe68c): a shared overlay accessibility controller (background inert, scroll lock, focus trap/restore, live announcements, in-overlay dirty-discard warning), semantic navigation/aria-current across all work areas, plus 44px targets, :focus-visible, contained table scrolling and 760/420px stacking. The slice is blocked for acceptance: the required browser matrix could not run (browser discovery returned []), so no screenshot/console/keyboard/mobile evidence exists. The nine-slice restructure is explicitly not declared complete. A pre-existing provenance test (ajl_lmr_writeback_status returning None) also still fails, unchanged and untouched by this work.
Code footprint: ~32.5k insertions / 17.5k deletions across 31 files. Seven new frontend modules (moc_workspace_view.js, moc_ajl_workflow_view.js, moc_checks_findings_view.js, moc_checks_lmr_view.js, moc_config_view.js, moc_history_view.js, moc_accessibility.js) plus moc_workspace.css; backend/moc_engine.py +1,185 lines and backend/main.py +335; 14 new test modules covering workflow projection, configuration, DDL projection, history, LMR workload, tenant context and frontend source rules.
Deployment-relevant: nothing to do. No new migrations, and no changes to deploy.sh, amms-backend.service, requirements.txt, or .github/. This release is frontend restructuring plus MOC-engine projection logic on the existing schema.
Upstream ArmanIrawan/AMMSTRO-AMMS: 671 commits total, still 0 tags / 0 releases / no CI. Fork is 123 commits behind.

2026-07-31 — 55 new commits: Report Centre V1, AMP Task Control & Lineage, Weekly/Event authority, inventory ops

Inventory operational workflows (12 commits, Jul 15–16): work-package tool-reservation integration stabilized (110e4ad); material issue & consumption (c29dbc3); tool checkout/return/inspection (45ae6fb); operational receiving (4a43a41); consolidated management workspace (93fdaa1); location-management workflow (1124c0d); plus an import-fix wave — root locations without a parent (1608849), import commit progress (e167367), tool import category mapping (41b6084), calibration-interval correction (b9a47e8), import source-location resolution (bda1797), catalog-definition validation (c01efdb).
Report Centre / Report Builder V1 (15 commits, Jul 17–18): implementation plan (52c9035) → builder registry foundation (5f8e50a), metadata shell (413e156), preview validation/provider (9bc330f) & preview controls (233c358), sorting/pagination/grouping (8ccd16f), private report definitions (7f1cdbb), shared reports & report runs (25c94e5), CSV & XLSX exports (2e2956d), report history & compatibility (39cefe2); reporting datasets — compliance forecast (14d33dd), Batch 11 (7d5ac23), audit exception (e11967b), curated aircraft-planning compliance report (c0b41c9); V1 hardening & docs (4f5bb32).
AMP Task Control (9 commits, Jul 18–31): remediation plan (f348a29), baseline protection (4c8182d), profile foundation (3bbe1b5), import control suggestions (23a540e), Slice 2 verification (80debd3), review backend (4dab642) & UI (8507104), presentation & reporting (adcadc3), migration sweep (1736f55).
AMP Task Lineage (8 commits, Jul 19–23): architecture decision (0615903) → foundation (999072c), matching workflow (f5db904), review UI (8672f9a), shadow mode (f40f22b), runtime adoption (2464321), transition stabilization (934131f), and removal of dangerous AMP task fallbacks (ed5ba48).
Weekly / operational-check / event authority (9 commits, Jul 23–31): operational-check policy & cadence (e3eeac1), shared accomplishment & occurrence foundation (0a970a3), Weekly dual-mode occurrence control (cb82db6), event-trigger activation backend (bb7da32) & operational integration/UI (ea3b6eb), Weekly route authority backend (8ebf9e5) & UI (b6d0831), AMP OOP (Out-of-Phase) activation authority (0cf007c) and OOP activation + Weekly bundling (ef977ab).
AMP defect fixes (2 commits, Jul 28): tenant stabilization defects (99c8b85), empty maintenance work-package loading (6ea0b91).
Deployment-relevant: 21 new migration files (migrations/2026_07_15_z_* through 2026_07_30_b_add_amp_oop_activation.sql) — inventory ops, report definitions/runs/artifacts, AMP task-control & lineage, operational-check policy, Weekly dual-mode, event-trigger activation, Weekly route authority, and AMP OOP activation schema. requirements.txt now pins openpyxl>=3.1,<4.0 for XLSX report exports. No changes to deploy.sh or amms-backend.service. Still no CI/CD.
Upstream ArmanIrawan/AMMSTRO-AMMS: 644 commits total, 0 tags/releases/CI. Fork is 96 commits behind.

2026-07-15 — 40 new commits: multi-tenancy rollout, LMR release workflow, Inventory/Materials/Tools module

Multi-tenancy rollout (16 commits, Jul 7–8): tenant context bound across techpub (ee18a19), PE/EO compliance (4fbd165), AMP tasks (a4c0024), workpackage & MOC operational flows (69db6d3, 72f3e8a), inventory linkage (bb0f036), audit/infra (e061bd3), RBAC role bindings scoped by tenant (61ae323); frontend tenant payload cleanup (78dc4fe) and backend tenant-fallback removal (4da751d); restored tenant-filtered dashboards (572a4c2); developer multi-tenant seed foundation (e1dfa5f); organization-aware login (a17122b); admin users filtered by session tenant (bd674bc); platform owner console foundation and first-admin onboarding (9a52e5f, 757fb2a); session cookies sent from Phase-In requests (ec497bb).
Tenant-scoping bug-fix wave (8 commits, Jul 9–10): phase-in tenant context for directive ingest (355807d), tenant context propagated from LDND events (10720da), AMP publish tenant scoping (55e7f9b), tenant-scoped forecast & due-WP generation (8cc58bf), tenant API smoke-path stabilization (218fd2b), phase-in normalization step removed (0c21bf6), dashboard tenant fleet counts fixed (f46cdd2), component management tenant filtering fixed (0fe7a2e).
LMR (Line Maintenance Release) workflow (6 commits, Jul 10–11): readiness read model & preview panel (5468f40, 2f2a7c6), WP execution scope history (233beeb), immutable release snapshot (8623c48), Maintenance LMR release action (b006378), browser print preview (6187955).
New Inventory/Materials/Tools module (8 commits, Jul 14–15): physical tracking alignment (5caea2c), CSV import staging → review/approval (9d192dc, c74870f) → approved-import promotion (4c00f39), material stock & Tool Store availability read models (726dc72, 684ff85), material request reservations (2414db4), tool request schedule reservations (735272e).
Deployment-relevant: 24 new migration files (migrations/2026_07_07_* through 2026_07_15_*) — tenant-scope columns across AMP/PE-EO/techpub/MOC/RBAC/infra, LMR tables, and the new inventory-tracking schema. No changes to deploy.sh, amms-backend.service, or requirements.txt. Still no CI/CD.
Upstream ArmanIrawan/AMMSTRO-AMMS: 589 commits total, 0 tags/releases/CI. Fork is 41 commits behind.

2026-07-06 — switched tracking to main repo (upstream)

8952167 Bind phase-in flows to tenant context — upstream-only commit (not yet in the fork): adds 2026_07_06_add_phase_in_tenant_scope.sql migration and ~250 lines of phase-in tenant-context tests. Continues the multi-tenant hardening arc.
Upstream ArmanIrawan/AMMSTRO-AMMS: 549 commits, no tags/releases/CI. Fork is 1 commit behind.

Deployment

No CI/CD — deployment is manual. deploy.sh builds a venv and runs uvicorn backend.main:app --host 0.0.0.0 --port 8000 (or ./deploy.sh smoke for the smoke test). amms-backend.service is a systemd unit running the same from /opt/amms as www-data. Config via AMMS_DB_PATH, AMMS_FRONTEND_DIR, AMMS_CORS_ORIGINS, PORT.

Since GitHub Releases/Deployments/Actions are unused, "deployment monitoring" = watching pushes to upstream main (plus alerting if tags, releases, or workflow files ever appear).