# soraou/archiveapp architecture

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

- Interactive diagram: https://gitdiagram.com/soraou/archiveapp
- Repository: https://github.com/soraou/archiveapp

## Overview

Office Document Archive is a local desktop finding aid: staff file scans with type-specific details and tags, then search, preview and open them later. The workflow starts in the Tkinter app, uses Archive business rules to validate and record metadata and stored files, and serves results in the main window. Separate capabilities cover type/tag administration, OCR-assisted filing, integrity checks, backups and restore, activity history, and an optional read-only browser view that excludes confidential documents. Relationships are limited to calls documented by excerpts, the source index, or README; unsampled internals are not inferred.

Main entry points: [`ui/main_window.py`](https://github.com/soraou/archiveapp/blob/main/ui/main_window.py) (Search window), [`services.py`](https://github.com/soraou/archiveapp/blob/main/services.py) (Archive rules), [`ui/add_dialog.py`](https://github.com/soraou/archiveapp/blob/main/ui/add_dialog.py) (File document), [`ui/pending_window.py`](https://github.com/soraou/archiveapp/blob/main/ui/pending_window.py) (Pending documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Desktop experience"]
  node_app["Application startup<br/>[app.py]"]
  node_main["Search window<br/>[main_window.py]"]
  node_common["Shared UI dialogs<br/>[common.py]"]
end

subgraph group_domain["Archive workflows"]
  node_add["File document<br/>[add_dialog.py]"]
  node_import["Bulk import<br/>[import_dialog.py]"]
  node_pending["Pending documents<br/>[pending_window.py]"]
  node_preview["Document preview<br/>[preview.py]"]
  node_types["Type administration<br/>[type_manager.py]"]
  node_type_dialogs["Type setup dialogs<br/>[type_dialogs.py]"]
  node_tags["Tag administration<br/>[tag_manager.py]"]
  node_ocr_ui["OCR review<br/>[ocr_dialog.py]"]
end

subgraph group_data["Archive data"]
  node_archive["Archive rules<br/>[services.py]"]
  node_database[("Archive database<br/>[db.py]")]
  node_files[("Scanned file storage<br/>[storage.py]")]
  node_ocr["OCR extraction<br/>[ocr.py]"]
end

subgraph group_ops["Operations and access"]
  node_backup_ui["Backup and checks<br/>[maintenance.py]"]
  node_backup["Backup engine<br/>[backup.py]"]
  node_restore["Restore utility<br/>[restore.py]"]
  node_recycle["Recycle bin<br/>[recycle_bin.py]"]
  node_activity["Activity history<br/>[activity_log.py]"]
  node_web_dialog["Browser controls<br/>[web_dialog.py]"]
  node_web["Read-only browser<br/>[webserver.py]"]
end

node_staff(("Office staff"))
node_operator(("Archive operator"))

node_staff -->|"starts"| node_app
node_app -->|"opens"| node_main
node_main -->|"searches"| node_archive
node_main -->|"opens filing"| node_add
node_main -->|"opens import"| node_import
node_main -->|"opens queue"| node_pending
node_main -->|"shows preview"| node_preview
node_main -->|"opens types"| node_types
node_main -->|"opens tags"| node_tags
node_main -->|"opens OCR"| node_ocr_ui
node_main -->|"opens tools"| node_backup_ui
node_main -->|"opens bin"| node_recycle
node_main -->|"opens log"| node_activity
node_main -->|"opens browser"| node_web_dialog
node_add -->|"files records"| node_archive
node_add -->|"previews scans"| node_preview
node_add -->|"configures types"| node_type_dialogs
node_import -->|"imports records"| node_archive
node_pending -->|"files selected"| node_add
node_pending -->|"loads records"| node_archive
node_types -->|"manages types"| node_archive
node_types -->|"edits fields"| node_type_dialogs
node_tags -->|"manages tags"| node_archive
node_ocr_ui -->|"updates records"| node_archive
node_archive -.->|"reads and writes"| node_database
node_archive -.->|"stores scans"| node_files
node_archive -.->|"extracts text"| node_ocr
node_backup_ui -->|"runs backup"| node_backup
node_backup_ui -->|"checks integrity"| node_archive
node_operator -->|"restores backup"| node_restore
node_restore -->|"reads backup"| node_backup
node_recycle -->|"manages deletions"| node_archive
node_activity -.->|"reads history"| node_archive
node_web_dialog -->|"controls server"| node_web
node_web -->|"searches publicly"| node_archive
node_operator -.->|"browses archive"| node_web

click node_app "https://github.com/soraou/archiveapp/blob/main/app.py"
click node_main "https://github.com/soraou/archiveapp/blob/main/ui/main_window.py"
click node_common "https://github.com/soraou/archiveapp/blob/main/ui/common.py"
click node_add "https://github.com/soraou/archiveapp/blob/main/ui/add_dialog.py"
click node_import "https://github.com/soraou/archiveapp/blob/main/ui/import_dialog.py"
click node_pending "https://github.com/soraou/archiveapp/blob/main/ui/pending_window.py"
click node_preview "https://github.com/soraou/archiveapp/blob/main/ui/preview.py"
click node_types "https://github.com/soraou/archiveapp/blob/main/ui/type_manager.py"
click node_type_dialogs "https://github.com/soraou/archiveapp/blob/main/ui/type_dialogs.py"
click node_tags "https://github.com/soraou/archiveapp/blob/main/ui/tag_manager.py"
click node_ocr_ui "https://github.com/soraou/archiveapp/blob/main/ui/ocr_dialog.py"
click node_archive "https://github.com/soraou/archiveapp/blob/main/services.py"
click node_database "https://github.com/soraou/archiveapp/blob/main/db.py"
click node_files "https://github.com/soraou/archiveapp/blob/main/storage.py"
click node_ocr "https://github.com/soraou/archiveapp/blob/main/ocr.py"
click node_backup_ui "https://github.com/soraou/archiveapp/blob/main/ui/maintenance.py"
click node_backup "https://github.com/soraou/archiveapp/blob/main/backup.py"
click node_restore "https://github.com/soraou/archiveapp/blob/main/restore.py"
click node_recycle "https://github.com/soraou/archiveapp/blob/main/ui/recycle_bin.py"
click node_activity "https://github.com/soraou/archiveapp/blob/main/ui/activity_log.py"
click node_web_dialog "https://github.com/soraou/archiveapp/blob/main/ui/web_dialog.py"
click node_web "https://github.com/soraou/archiveapp/blob/main/webserver.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_main,node_common toneBlue
class node_add,node_import,node_pending,node_preview,node_types,node_type_dialogs,node_tags,node_ocr_ui toneAmber
class node_archive,node_database,node_files,node_ocr toneMint
class node_backup_ui,node_backup,node_restore,node_recycle,node_activity,node_web_dialog,node_web toneRose
class node_staff,node_operator toneIndigo
```

## Components

### Desktop experience

- [Application startup](https://github.com/soraou/archiveapp/blob/main/app.py): `app.py`
- [Search window](https://github.com/soraou/archiveapp/blob/main/ui/main_window.py): `ui/main_window.py`
- [Shared UI dialogs](https://github.com/soraou/archiveapp/blob/main/ui/common.py): `ui/common.py`

### Archive workflows

- [File document](https://github.com/soraou/archiveapp/blob/main/ui/add_dialog.py): `ui/add_dialog.py`
- [Bulk import](https://github.com/soraou/archiveapp/blob/main/ui/import_dialog.py): `ui/import_dialog.py`
- [Pending documents](https://github.com/soraou/archiveapp/blob/main/ui/pending_window.py): `ui/pending_window.py`
- [Document preview](https://github.com/soraou/archiveapp/blob/main/ui/preview.py): `ui/preview.py`
- [Type administration](https://github.com/soraou/archiveapp/blob/main/ui/type_manager.py): `ui/type_manager.py`
- [Type setup dialogs](https://github.com/soraou/archiveapp/blob/main/ui/type_dialogs.py): `ui/type_dialogs.py`
- [Tag administration](https://github.com/soraou/archiveapp/blob/main/ui/tag_manager.py): `ui/tag_manager.py`
- [OCR review](https://github.com/soraou/archiveapp/blob/main/ui/ocr_dialog.py): `ui/ocr_dialog.py`

### Archive data

- [Archive rules](https://github.com/soraou/archiveapp/blob/main/services.py): `services.py`
- [Archive database](https://github.com/soraou/archiveapp/blob/main/db.py): `db.py`
- [Scanned file storage](https://github.com/soraou/archiveapp/blob/main/storage.py): `storage.py`
- [OCR extraction](https://github.com/soraou/archiveapp/blob/main/ocr.py): `ocr.py`

### Operations and access

- [Backup and checks](https://github.com/soraou/archiveapp/blob/main/ui/maintenance.py): `ui/maintenance.py`
- [Backup engine](https://github.com/soraou/archiveapp/blob/main/backup.py): `backup.py`
- [Restore utility](https://github.com/soraou/archiveapp/blob/main/restore.py): `restore.py`
- [Recycle bin](https://github.com/soraou/archiveapp/blob/main/ui/recycle_bin.py): `ui/recycle_bin.py`
- [Activity history](https://github.com/soraou/archiveapp/blob/main/ui/activity_log.py): `ui/activity_log.py`
- [Browser controls](https://github.com/soraou/archiveapp/blob/main/ui/web_dialog.py): `ui/web_dialog.py`
- [Read-only browser](https://github.com/soraou/archiveapp/blob/main/webserver.py): `webserver.py`

### Other components

- **Office staff**
- **Archive operator**

## Connections

- Office staff → Application startup: starts (evidence: `README.md`)
- Application startup → Search window: opens (evidence: `app.py`)
- Search window → Archive rules: searches (evidence: `ui/main_window.py`)
- Search window → File document: opens filing (evidence: `ui/main_window.py`)
- Search window → Bulk import: opens import (evidence: `ui/main_window.py`)
- Search window → Pending documents: opens queue (evidence: `ui/main_window.py`)
- Search window → Document preview: shows preview (evidence: `ui/main_window.py`)
- Search window → Type administration: opens types (evidence: `ui/main_window.py`)
- Search window → Tag administration: opens tags (evidence: `ui/main_window.py`)
- Search window → OCR review: opens OCR (evidence: `ui/main_window.py`)
- Search window → Backup and checks: opens tools (evidence: `ui/main_window.py`)
- Search window → Recycle bin: opens bin (evidence: `ui/main_window.py`)
- Search window → Activity history: opens log (evidence: `ui/main_window.py`)
- Search window → Browser controls: opens browser (evidence: `ui/main_window.py`)
- File document → Archive rules: files records (evidence: `ui/add_dialog.py`)
- File document → Document preview: previews scans (evidence: `ui/add_dialog.py`)
- File document → Type setup dialogs: configures types (evidence: `ui/add_dialog.py`)
- Bulk import → Archive rules: imports records (evidence: `ui/import_dialog.py`)
- Pending documents → File document: files selected (evidence: `ui/pending_window.py`)
- Pending documents → Archive rules: loads records (evidence: `ui/pending_window.py`)
- Type administration → Archive rules: manages types (evidence: `ui/type_manager.py`)
- Type administration → Type setup dialogs: edits fields (evidence: `ui/type_manager.py`)
- Tag administration → Archive rules: manages tags (evidence: `ui/tag_manager.py`)
- OCR review → Archive rules: updates records (evidence: `ui/ocr_dialog.py`)
- Archive rules → Archive database: reads and writes (evidence: `services.py`)
- Archive rules → Scanned file storage: stores scans (evidence: `services.py`)
- Archive rules → OCR extraction: extracts text (evidence: `services.py`)
- Backup and checks → Backup engine: runs backup (evidence: `ui/maintenance.py`)
- Backup and checks → Archive rules: checks integrity (evidence: `ui/maintenance.py`)
- Archive operator → Restore utility: restores backup (evidence: `README.md`)
- Restore utility → Backup engine: reads backup (evidence: `restore.py`)
- Recycle bin → Archive rules: manages deletions (evidence: `ui/recycle_bin.py`)
- Activity history → Archive rules: reads history
- Browser controls → Read-only browser: controls server (evidence: `ui/web_dialog.py`)
- Read-only browser → Archive rules: searches publicly (evidence: `webserver.py`)
- Archive operator → Read-only browser: browses archive (evidence: `README.md`)
