# textailes/mulan architecture

> Architecture diagram of the GitHub repository textailes/mulan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/textailes/mulan
- Repository: https://github.com/textailes/mulan

## Overview

MulAn is a single-user multispectral image web app: users convert ordered BMP channels to TIFF, upload and inspect TIFF channels, then create and export semantic masks. The React pages call Flask HTTP adapters; services perform conversion, preview generation, and mask editing, backed by UUID-scoped filesystem resources. The graph preserves the documented workflow and annotation/history/export capabilities. Several API and service excerpts are partial, so unsampled operations are linked only where README or indexed references support the relationship.

Main entry points: [`frontend/src/App.tsx`](https://github.com/textailes/mulan/blob/master/frontend/src/App.tsx) (App routes), [`frontend/src/api/client.ts`](https://github.com/textailes/mulan/blob/master/frontend/src/api/client.ts) (API client), [`frontend/src/pages/AnnotatorPage.tsx`](https://github.com/textailes/mulan/blob/master/frontend/src/pages/AnnotatorPage.tsx) (Mask annotator), [`frontend/src/pages/ViewerPage.tsx`](https://github.com/textailes/mulan/blob/master/frontend/src/pages/ViewerPage.tsx) (TIFF viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_app["App routes<br/>[App.tsx]"]
  node_convert_page["BMP converter<br/>[ConvertPage.tsx]"]
  node_convert_result["Conversion result"]
  node_viewer["TIFF viewer<br/>[ViewerPage.tsx]"]
  node_annotator["Mask annotator<br/>[AnnotatorPage.tsx]"]
  node_controls["Image controls<br/>[ImageControls.tsx]"]
  node_dropzone["Upload dropzone<br/>[UploadDropzone.tsx]"]
  node_tools["Annotation tools<br/>[annotationTools.ts]"]
  node_unsaved["Unsaved state<br/>[UnsavedContext.tsx]"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_public_api["Public API<br/>[public.py]"]
  node_internal_api["Internal API<br/>[internal.py]"]
end

subgraph group_processing["Image processing"]
  node_conversion["BMP conversion<br/>[conversion.py]"]
  node_images["Image service<br/>[images.py]"]
  node_annotations["Annotation service<br/>[annotations.py]"]
end

subgraph group_persistence["Resource storage"]
  node_store[("Filesystem store<br/>[filesystem.py]")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_convert_page
node_app -->|"routes to"| node_convert_result
node_app -->|"routes to"| node_viewer
node_app -->|"routes to"| node_annotator
node_convert_page -->|"renders"| node_dropzone
node_viewer -->|"renders"| node_controls
node_viewer -->|"renders"| node_dropzone
node_annotator -->|"renders"| node_controls
node_annotator -->|"renders"| node_dropzone
node_annotator -->|"uses"| node_tools
node_app -->|"provides state"| node_unsaved
node_convert_page -->|"requests conversion"| node_client
node_convert_result -->|"requests result"| node_client
node_viewer -->|"requests image"| node_client
node_annotator -->|"requests annotation"| node_client
node_client -->|"HTTP requests"| node_public_api
node_client -->|"HTTP requests"| node_internal_api
node_public_api -->|"calls"| node_images
node_public_api -->|"calls"| node_conversion
node_public_api -->|"calls"| node_annotations
node_internal_api -->|"calls"| node_annotations
node_conversion -.->|"stores resources"| node_store
node_images -->|"reads and writes"| node_store
node_annotations -->|"uses image service"| node_images
node_annotations -->|"reads and writes"| node_store

click node_app "https://github.com/textailes/mulan/blob/master/frontend/src/App.tsx"
click node_convert_page "https://github.com/textailes/mulan/blob/master/frontend/src/pages/ConvertPage.tsx"
click node_convert_result "https://github.com/textailes/mulan/blob/master/frontend/src/pages/ConvertResultPage.tsx"
click node_viewer "https://github.com/textailes/mulan/blob/master/frontend/src/pages/ViewerPage.tsx"
click node_annotator "https://github.com/textailes/mulan/blob/master/frontend/src/pages/AnnotatorPage.tsx"
click node_controls "https://github.com/textailes/mulan/blob/master/frontend/src/components/ImageControls.tsx"
click node_dropzone "https://github.com/textailes/mulan/blob/master/frontend/src/components/UploadDropzone.tsx"
click node_tools "https://github.com/textailes/mulan/blob/master/frontend/src/components/annotationTools.ts"
click node_unsaved "https://github.com/textailes/mulan/blob/master/frontend/src/context/UnsavedContext.tsx"
click node_client "https://github.com/textailes/mulan/blob/master/frontend/src/api/client.ts"
click node_public_api "https://github.com/textailes/mulan/blob/master/backend/mulan/api/public.py"
click node_internal_api "https://github.com/textailes/mulan/blob/master/backend/mulan/api/internal.py"
click node_conversion "https://github.com/textailes/mulan/blob/master/backend/mulan/services/conversion.py"
click node_images "https://github.com/textailes/mulan/blob/master/backend/mulan/services/images.py"
click node_annotations "https://github.com/textailes/mulan/blob/master/backend/mulan/services/annotations.py"
click node_store "https://github.com/textailes/mulan/blob/master/backend/mulan/storage/filesystem.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_convert_page,node_convert_result,node_viewer,node_annotator,node_controls,node_dropzone,node_tools,node_unsaved,node_client,node_user toneBlue
class node_public_api,node_internal_api toneAmber
class node_conversion,node_images,node_annotations toneMint
class node_store toneRose
```

## Components

### Web interface

- [App routes](https://github.com/textailes/mulan/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [BMP converter](https://github.com/textailes/mulan/blob/master/frontend/src/pages/ConvertPage.tsx): `frontend/src/pages/ConvertPage.tsx`
- [Conversion result](https://github.com/textailes/mulan/blob/master/frontend/src/pages/ConvertResultPage.tsx): `frontend/src/pages/ConvertResultPage.tsx`
- [TIFF viewer](https://github.com/textailes/mulan/blob/master/frontend/src/pages/ViewerPage.tsx): `frontend/src/pages/ViewerPage.tsx`
- [Mask annotator](https://github.com/textailes/mulan/blob/master/frontend/src/pages/AnnotatorPage.tsx): `frontend/src/pages/AnnotatorPage.tsx`
- [Image controls](https://github.com/textailes/mulan/blob/master/frontend/src/components/ImageControls.tsx): `frontend/src/components/ImageControls.tsx`
- [Upload dropzone](https://github.com/textailes/mulan/blob/master/frontend/src/components/UploadDropzone.tsx): `frontend/src/components/UploadDropzone.tsx`
- [Annotation tools](https://github.com/textailes/mulan/blob/master/frontend/src/components/annotationTools.ts): `frontend/src/components/annotationTools.ts`
- [Unsaved state](https://github.com/textailes/mulan/blob/master/frontend/src/context/UnsavedContext.tsx): `frontend/src/context/UnsavedContext.tsx`
- [API client](https://github.com/textailes/mulan/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### HTTP API

- [Public API](https://github.com/textailes/mulan/blob/master/backend/mulan/api/public.py): `backend/mulan/api/public.py`
- [Internal API](https://github.com/textailes/mulan/blob/master/backend/mulan/api/internal.py): `backend/mulan/api/internal.py`

### Image processing

- [BMP conversion](https://github.com/textailes/mulan/blob/master/backend/mulan/services/conversion.py): `backend/mulan/services/conversion.py`
- [Image service](https://github.com/textailes/mulan/blob/master/backend/mulan/services/images.py): `backend/mulan/services/images.py`
- [Annotation service](https://github.com/textailes/mulan/blob/master/backend/mulan/services/annotations.py): `backend/mulan/services/annotations.py`

### Resource storage

- [Filesystem store](https://github.com/textailes/mulan/blob/master/backend/mulan/storage/filesystem.py): `backend/mulan/storage/filesystem.py`

### Other components

- **User**

## Connections

- User → App routes: uses (evidence: `README.md`)
- App routes → BMP converter: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Conversion result: routes to (evidence: `frontend/src/App.tsx`)
- App routes → TIFF viewer: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Mask annotator: routes to (evidence: `frontend/src/App.tsx`)
- BMP converter → Upload dropzone: renders (evidence: `frontend/src/pages/ConvertPage.tsx`)
- TIFF viewer → Image controls: renders (evidence: `frontend/src/pages/ViewerPage.tsx`)
- TIFF viewer → Upload dropzone: renders (evidence: `frontend/src/pages/ViewerPage.tsx`)
- Mask annotator → Image controls: renders (evidence: `frontend/src/pages/AnnotatorPage.tsx`)
- Mask annotator → Upload dropzone: renders (evidence: `frontend/src/pages/AnnotatorPage.tsx`)
- Mask annotator → Annotation tools: uses (evidence: `frontend/src/pages/AnnotatorPage.tsx`)
- App routes → Unsaved state: provides state (evidence: `frontend/src/App.tsx`)
- BMP converter → API client: requests conversion (evidence: `frontend/src/pages/ConvertPage.tsx`)
- Conversion result → API client: requests result (evidence: `frontend/src/pages/ConvertResultPage.tsx`)
- TIFF viewer → API client: requests image (evidence: `frontend/src/pages/ViewerPage.tsx`)
- Mask annotator → API client: requests annotation (evidence: `frontend/src/pages/AnnotatorPage.tsx`)
- API client → Public API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- API client → Internal API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- Public API → Image service: calls (evidence: `backend/mulan/api/public.py`)
- Public API → BMP conversion: calls (evidence: `backend/mulan/api/public.py`)
- Public API → Annotation service: calls (evidence: `backend/mulan/api/public.py`)
- Internal API → Annotation service: calls (evidence: `backend/mulan/api/internal.py`)
- BMP conversion → Filesystem store: stores resources
- Image service → Filesystem store: reads and writes (evidence: `backend/mulan/services/images.py`)
- Annotation service → Image service: uses image service (evidence: `backend/mulan/services/annotations.py`)
- Annotation service → Filesystem store: reads and writes (evidence: `backend/mulan/services/annotations.py`)
