iron/docs/architecture.md

Architecture

Iron is an async Python modular monolith with a React single-page Web app.

System Overview

Browser UI
  |
FastAPI app
  |
Services
  |
Repositories
  |
SQLite metadata database
  |
Storage adapters: local, S3

Backend

Core stack:

• FastAPI
• SQLAlchemy 2.x async ORM
• SQLite via aiosqlite
• Alembic migrations
• durable in-process jobs stored in SQLite

Important packages:

• app/api/: route handlers and dependency wiring
• app/services/: business logic
• app/repositories/: database access
• app/models/: SQLAlchemy entities
• app/schemas/: API schemas
• app/adapters/storage/: storage backends

Frontend

Core stack:

• Vite
• React
• TypeScript
• React Router
• TanStack Query

Source lives in frontend/. Built assets are emitted into app/web/dist/ and served by FastAPI at /app.

Data Model

Main tables:

• users
• auth_sessions
• directories
• file_entries
• file_versions
• blobs
• blob_replicas
• backends
• upload_sessions
• upload_session_parts
• jobs
• placement_policies
• preview_artifacts
• cache_entries

Design principles:

• logical namespace is separate from physical storage placement
• files have immutable content versions
• physical content is represented as blobs and replicas
• user-facing deletion uses recycle-bin semantics
• jobs are durable and retryable
• backend-specific configuration stays behind adapter boundaries

Upload And Read Path

Uploads use tus transport under /files.

Flow:

1. create upload session
2. append bytes with PATCH
3. finalize through the API
4. create file metadata, version, blob, and local replica
5. enqueue replication or preview jobs when needed

Read path:

1. resolve file and current version
2. find the best local or cached blob
3. if needed, materialize a ready remote replica into cache
4. serve download, preview, or range stream

Browser File Access

JSON APIs use bearer-token authorization through the shared frontend API client.

Browser preview and download must not use naked /api/files/... media URLs in img, iframe, video, or window.open. Fetch file content with authorization, create an object URL, use it, then revoke it.

This is covered by the Playwright E2E flow.

Jobs

Jobs are stored in SQLite and executed by the in-process job loop.

Current job types include:

• blob replication
• preview artifact generation
• backend health checks
• full reconcile
• file reconcile

Every job should be safe to retry.