FlightArchive is a containerized flight-history application written with Python, FastAPI, React 19, TypeScript, and Material UI. It uses RemappableFileGateway (RFG) for read-only source discovery, virtual-path mappings, resource delivery, and hashes.
It follows these rules:
- flight, catalog, and boarding-pass-layout data is atomically persisted by the backend
- resources are selected from an RFG resource root and business records retain only classified virtual paths
- resource mappings can be inspected and manually re-matched without editing virtual paths
- thumbnails are disposable derived cache data; they never enter business data
- fingerprint storage is limited to classified resources directly bound to saved flight boarding passes or attachments, or to a saved airline logo
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
RFG owns the read-only resource root and <data>/rfg/mapping.json. FlightArchive owns <data>/flightarchive/v1/business-data.json. A separate cache root stores rebuildable thumbnail objects and is never part of business data.
On first start, FlightArchive atomically seeds the restart-only, user-editable configuration file <RFG_DATA_DIR>/flightarchive/v1/preview-config.json. It is separate from both BusinessData and the disposable thumbnail cache. At startup, the path must be a regular file, must not be a symbolic link, and must be no larger than 64 KiB. The file must also be valid version 1 configuration; any violation blocks startup until it is corrected. Changes take effect only after restarting the backend.
{
"schemaVersion": 1,
"thumbnails": {
"maxSourceBytes": 268435456,
"maxSourcePixels": 100000000,
"maxDimension": 512,
"quality": 82,
"jobConcurrency": 2
},
"rfg": {
"pillowImageMaxPixels": 100000000
}
}thumbnails.maxSourceBytes defaults to 256 MiB. The inclusive ranges are: maxSourceBytes 1 MiB–1 GiB, maxSourcePixels 1,000,000–500,000,000, maxDimension 1–2048, quality 0–100, jobConcurrency 1–2, and pillowImageMaxPixels 1,000,000–500,000,000. Every scalar must be a strict JSON integer, and the document must contain exactly the documented keys. Unknown keys, missing keys, non-integers, and out-of-range values block startup. Raising the byte or pixel limits, or job concurrency, can increase memory use; concurrent image work has a corresponding memory cost. Changing thumbnail settings invalidates and reprofiles the thumbnail cache. All configuration changes are restart-only.
rfg.pillowImageMaxPixels is the only supported host-configurable RFG image safety setting. It is applied before RFG initializes and affects perceptual hashes. RFG ZIP guards, hash capacity, and internal thresholds are not configurable through this file.
FlightArchive provides a responsive flight dashboard, flight and flight-reference (airline / airport / aircraft type) catalog editing, resource selection and classification, mapping review with ignore and re-match operations, business-bound resource fingerprints, and a boarding-pass crop & layout tool.
Run the following container commands from the repository root.
Build Docker Image:
docker build -f app/Dockerfile -t flightarchive:local appRun Docker Image:
docker run -d \
--name=flightarchive \
--restart=unless-stopped \
-p 127.0.0.1:8080:8080/tcp \
-v /path/for/resources:/resource:ro \
-v /path/for/data:/data \
flightarchive:localPublished images: Each published GitHub Release tag is used directly as the image tag (without version normalization) and also updates latest:
docker pull ghcr.io/mehver/flightarchive:<release-tag>
docker pull docker.io/mehver/flightarchive:<release-tag>Release assets also include separately loadable linux/amd64 and linux/arm64 Docker image tarballs.
| Parameter | Function |
|---|---|
-p 127.0.0.1:8080:8080/tcp |
HTTP web interface |
-v /path/for/resources:/resource:ro |
Existing RFG resource root, read-only |
-v /path/for/data:/data |
RFG mapping and FlightArchive business data |
-v /path/for/cache:/cache |
Optional rebuildable thumbnail cache |
Open http://localhost:8080 after the container starts. Without the optional cache mount, /cache remains an ordinary disposable container directory.
The Notifications & Tasks drawer combines session-only notifications with backend-persisted task history. The application loads the newest three existing UTC log days into its global task store, shares that history with the drawer, and loads older days while scrolling. While any task is queued or running, it polls even when the drawer is closed and stops after tasks reach terminal states. Active tasks appear in a dedicated first group. Other entries retain their valid UTC instants, including future instants, and are grouped for display by the user's local activity date with newest dates first; only invalid times fall back to the current time. Session notifications exist only for the current session and clear on reload; task history persists in backend JSONL logs.
Polling also tracks the creation dates of known active tasks outside the newest three days, without moving the older-history cursor. Current-session task phases notify once regardless of whether POST or GET arrives first; historical loading and progress-only updates do not replay notifications. Task-history loading errors do not block session notifications. Closing a resource picker does not cancel an already submitted ignore operation: success is reported globally, while failure is global if the original dialog is closed; an old operation cannot change a newly opened dialog.
Task feedback is stored in the fixed <RFG_DATA_DIR>/flightarchive/log/tasks/ directory and retained across restarts. The old flightarchive/log/task/ directory is not read, migrated, or deleted. The backend worker executes its real in-memory FIFO queue; logs are feedback, not commands or a replay source. Reading interrupted history conservatively records failure, preserving successful items; without a reliable terminal record, success is not inferred. A failed task can have zero failed items and is then shown as Result Unconfirmed. Task timestamps use UTC with six fractional digits and +00:00; the frontend also accepts Z and compares instants without losing microsecond identity.
Docker Compose:
cp app/.env.example app/.env
docker compose --env-file app/.env -f app/compose.yaml up --buildFor a persistent or high-speed thumbnail cache, set FLIGHTARCHIVE_CACHE_HOST_PATH and run:
docker compose --env-file app/.env -f app/compose.yaml -f app/compose.cache-host.yaml up --buildThe override mounts only /cache; the resource mount remains read-only and the data mount retains RFG mapping and business state.
Requirements
- Docker
- Node.js v22 or later for frontend development
- Python 3.10 or later for backend development and tests
Install Dependency
cd app/frontend
pnpm install
cd ../backend
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txtFrontend Development
cd app/frontend
pnpm devFrontend Compile
cd app/frontend
pnpm buildBackend Server
cd app/backend
RFG_RESOURCE_PATH=/path/for/resources \
RFG_DATA_DIR=/path/for/data \
python -m flightarchiveTests / Typecheck
cd app/backend
python -m pytest tests -q
cd ../frontend
pnpm exec vitest run --maxWorkers=4
pnpm typecheckBuild Docker Image
docker build -f app/Dockerfile -t flightarchive:local appOn Windows, tools/BuildAll.bat builds the same local image. tools/BuildAndRunContainer.bat is a Windows helper that cleans local build artifacts, prompts for host mappings, and starts a detached container. On other platforms, use the docker run command in Usage.
All dependencies are open-source and licensed under permissive licenses. No copyleft (for example GPL or AGPL) components are included.
- Python
- Node.js
- React 19 + Vite
- Docker
node:22-bookworm-slimpython:3.14-slim
This project is released under the BSD 3-Clause License. Code may be reused with proper attribution.
Copyright (c) 2026 Mehver (https://github.com/Mehver). All rights reserved.
All dependencies are open-source and licensed under permissive licenses. No copyleft (for example GPL or AGPL) components are included.





