mehver/flightarchive repository overview

⁠FlightArchive v1.0.1

English | 简体中文⁠

⁠1 Description

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

⁠1.1 Resource Model

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.

⁠1.2 Preview Configuration

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. The file must be valid version 1 configuration; an invalid file 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. Raising it, the source-pixel limit, or job concurrency can increase memory use; concurrent image work has a corresponding memory cost. Changing thumbnail settings invalidates and reprofiles the thumbnail cache.

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.

⁠1.3 Current Features

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.

⁠2 Usage

Run the following container commands from the repository root.

Build Docker Image:

docker build -f app/Dockerfile -t flightarchive:local app

Run 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:local

Published 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.

Open http://localhost:8080⁠ after the container starts. Without the optional cache mount, /cache remains an ordinary disposable container directory.

The Activity & Tasks drawer combines session-only operation feedback with background-task history grouped by log date; activity is not persisted across reloads. Task history is loaded only while the drawer is open, starts with the newest three existing log dates, loads older dates while scrolling, and polls only while an active task needs a fresh latest-page snapshot.

Docker Compose:

cp app/.env.example app/.env
docker compose --env-file app/.env -f app/compose.yaml up --build

For 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 --build

The override mounts only /cache; the resource mount remains read-only and the data mount retains RFG mapping and business state.

⁠3 Development

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.txt

Frontend Development

cd app/frontend
pnpm dev

Frontend Compile

cd app/frontend
pnpm build

Backend Server

cd app/backend
RFG_RESOURCE_PATH=/path/for/resources \
RFG_DATA_DIR=/path/for/data \
python -m flightarchive

Tests / Typecheck

cd app/backend
python -m pytest tests -q

cd ../frontend
pnpm exec vitest run --maxWorkers=4
pnpm typecheck

Build Docker Image

docker build -f app/Dockerfile -t flightarchive:local app

On 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⁠.

⁠4 Built With

• Python
  • FastAPI⁠
  • Uvicorn⁠
  • RemappableFileGateway⁠
  • Pillow⁠
• Node.js
  • React 19 + Vite
    • Material UI⁠
    • Vitest⁠
• Docker
  • node:22-bookworm-slim
  • python:3.14-slim

⁠5 License

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.