# nicohaider/sampling-tool architecture

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

- Interactive diagram: https://gitdiagram.com/nicohaider/sampling-tool
- Repository: https://github.com/nicohaider/sampling-tool

## Overview

BDO Audit Sampling Tool is a desktop application for reproducible, documented ISAE-3402 audit sampling. The main workflow is project setup/open, spreadsheet import, sample configuration and draw, review, then report export. SQLite projects hold datasets, samples, engagement state and audit events; the README also describes undo/redo, presets, dashboard and audit-trail views. The sampled excerpts show controller ownership, worker tasks, persistence and exports; other capabilities are included where supported by the README, with uncertain internal wiring omitted.

Main entry points: [`src/sampling_tool/ui/controllers/workspace_controller.py`](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/workspace_controller.py) (Workspace operations), [`src/sampling_tool/persistence/repositories.py`](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/repositories.py) (Project repositories), [`src/sampling_tool/ui/workers/tasks.py`](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/workers/tasks.py) (Import and export tasks), [`src/sampling_tool/ui/main_window.py`](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/main_window.py) (Main window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workflow"]
  node_main_window["Main window<br/>[main_window.py]"]
  node_main_controller["Main controller<br/>[main_controller.py]"]
  node_engagement_controller["Project lifecycle"]
  node_workspace_controller["Workspace operations"]
  node_selection_controller["Dataset and sample selection"]
  node_dashboard_views["Table, sidebar, dashboard, audit view<br/>[dashboard_view.py]"]
  node_worker["Background task runner<br/>[task_worker.py]"]
  node_tasks["Import and export tasks<br/>[tasks.py]"]
end

subgraph group_sampling["Import and sampling"]
  node_importer["Excel / CSV importer<br/>[importer.py]"]
  node_preflight["Import preview and options"]
  node_sampling_core["Sampling algorithms<br/>[sampling.py]"]
  node_sampling_models["Sampling configuration and models<br/>[models.py]"]
end

subgraph group_storage["Project data"]
  node_database[("Project SQLite database<br/>[database.py]")]
  node_repositories["Project repositories<br/>[repositories.py]"]
  node_audit_logger["Audit event logger<br/>[logger.py]"]
  node_snapshot_manager["Project snapshots<br/>[version_manager.py]"]
end

subgraph group_reporting["Review and reporting"]
  node_export_controller["Export controller"]
  node_exporter["Sample and Excel exports<br/>[exporter.py]"]
  node_report_exporters["PDF and HTML reports<br/>[pdf_report.py]"]
  node_multi_report["Multi-sheet project report"]
end

subgraph group_preferences["App preferences"]
  node_preset_store["Sampling presets<br/>[preset_store.py]"]
  node_settings_store["Application settings<br/>[settings_store.py]"]
end

node_auditor(("Auditor"))
node_source_files["Excel / CSV files"]
node_report_recipient(("Report recipient"))

node_auditor -->|"uses"| node_main_window
node_main_window -->|"dispatches signals"| node_main_controller
node_main_controller -->|"routes lifecycle"| node_engagement_controller
node_main_controller -->|"routes operations"| node_workspace_controller
node_main_controller -->|"routes selection"| node_selection_controller
node_engagement_controller -->|"opens project"| node_database
node_engagement_controller -->|"creates snapshots"| node_snapshot_manager
node_engagement_controller -->|"loads engagement"| node_repositories
node_workspace_controller -->|"requests import options"| node_preflight
node_source_files -->|"previews source"| node_preflight
node_preflight -->|"returns import choices"| node_workspace_controller
node_workspace_controller -->|"starts tasks"| node_worker
node_worker -->|"runs task"| node_tasks
node_tasks -->|"reads source"| node_importer
node_importer -->|"reads rows"| node_source_files
node_tasks -->|"stores dataset"| node_repositories
node_workspace_controller -->|"performs draw"| node_sampling_core
node_sampling_core -->|"uses configuration"| node_sampling_models
node_workspace_controller -->|"reads and saves samples"| node_repositories
node_workspace_controller -->|"records actions"| node_audit_logger
node_audit_logger -->|"appends events"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_selection_controller -->|"loads selections"| node_repositories
node_selection_controller -->|"updates display"| node_dashboard_views
node_database -->|"supplies project data"| node_dashboard_views
node_export_controller -->|"reads export data"| node_repositories
node_export_controller -->|"starts export tasks"| node_worker
node_tasks -->|"writes sample Excel"| node_exporter
node_tasks -->|"renders PDF or HTML"| node_report_exporters
node_tasks -->|"writes Excel report"| node_multi_report
node_export_controller -->|"records exports"| node_audit_logger
node_report_exporters -->|"produces reports"| node_report_recipient
node_exporter -->|"produces workbook"| node_report_recipient
node_main_window -->|"manages presets"| node_preset_store
node_main_window -->|"saves settings"| node_settings_store
node_workspace_controller -->|"loads sampling presets"| node_preset_store

click node_main_window "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/main_window.py"
click node_main_controller "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/main_controller.py"
click node_engagement_controller "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/engagement_controller.py"
click node_workspace_controller "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/workspace_controller.py"
click node_selection_controller "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/selection_controller.py"
click node_dashboard_views "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/widgets/dashboard_view.py"
click node_worker "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/workers/task_worker.py"
click node_tasks "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/workers/tasks.py"
click node_importer "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/importer.py"
click node_preflight "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/import_preflight.py"
click node_sampling_core "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/core/sampling.py"
click node_sampling_models "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/core/models.py"
click node_database "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/database.py"
click node_repositories "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/repositories.py"
click node_audit_logger "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/audit/logger.py"
click node_snapshot_manager "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/version_manager.py"
click node_export_controller "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/export_controller.py"
click node_exporter "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/exporter.py"
click node_report_exporters "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/pdf_report.py"
click node_multi_report "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/multi_report_exporter.py"
click node_preset_store "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/preset_store.py"
click node_settings_store "https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/settings_store.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_main_window,node_main_controller,node_engagement_controller,node_workspace_controller,node_selection_controller,node_dashboard_views,node_worker,node_tasks toneBlue
class node_importer,node_preflight,node_sampling_core,node_sampling_models toneAmber
class node_database,node_repositories,node_audit_logger,node_snapshot_manager toneMint
class node_export_controller,node_exporter,node_report_exporters,node_multi_report toneRose
class node_preset_store,node_settings_store,node_auditor,node_source_files,node_report_recipient toneIndigo
```

## Components

### Desktop workflow

- [Main window](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/main_window.py): `src/sampling_tool/ui/main_window.py`
- [Main controller](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/main_controller.py): `src/sampling_tool/ui/controllers/main_controller.py`
- [Project lifecycle](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/engagement_controller.py): `src/sampling_tool/ui/controllers/engagement_controller.py`
- [Workspace operations](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/workspace_controller.py): `src/sampling_tool/ui/controllers/workspace_controller.py`
- [Dataset and sample selection](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/selection_controller.py): `src/sampling_tool/ui/controllers/selection_controller.py`
- [Table, sidebar, dashboard, audit view](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/widgets/dashboard_view.py): `src/sampling_tool/ui/widgets/dashboard_view.py`
- [Background task runner](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/workers/task_worker.py): `src/sampling_tool/ui/workers/task_worker.py`
- [Import and export tasks](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/workers/tasks.py): `src/sampling_tool/ui/workers/tasks.py`

### Import and sampling

- [Excel / CSV importer](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/importer.py): `src/sampling_tool/io/importer.py`
- [Import preview and options](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/import_preflight.py): `src/sampling_tool/io/import_preflight.py`
- [Sampling algorithms](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/core/sampling.py): `src/sampling_tool/core/sampling.py`
- [Sampling configuration and models](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/core/models.py): `src/sampling_tool/core/models.py`

### Project data

- [Project SQLite database](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/database.py): `src/sampling_tool/persistence/database.py`
- [Project repositories](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/repositories.py): `src/sampling_tool/persistence/repositories.py`
- [Audit event logger](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/audit/logger.py): `src/sampling_tool/audit/logger.py`
- [Project snapshots](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/persistence/version_manager.py): `src/sampling_tool/persistence/version_manager.py`

### Review and reporting

- [Export controller](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/controllers/export_controller.py): `src/sampling_tool/ui/controllers/export_controller.py`
- [Sample and Excel exports](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/exporter.py): `src/sampling_tool/io/exporter.py`
- [PDF and HTML reports](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/pdf_report.py): `src/sampling_tool/io/pdf_report.py`
- [Multi-sheet project report](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/io/multi_report_exporter.py): `src/sampling_tool/io/multi_report_exporter.py`

### App preferences

- [Sampling presets](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/preset_store.py): `src/sampling_tool/ui/preset_store.py`
- [Application settings](https://github.com/nicohaider/sampling-tool/blob/main/src/sampling_tool/ui/settings_store.py): `src/sampling_tool/ui/settings_store.py`

### Other components

- **Auditor**
- **Excel / CSV files**
- **Report recipient**

## Connections

- Auditor → Main window: uses
- Main window → Main controller: dispatches signals
- Main controller → Project lifecycle: routes lifecycle
- Main controller → Workspace operations: routes operations
- Main controller → Dataset and sample selection: routes selection
- Project lifecycle → Project SQLite database: opens project
- Project lifecycle → Project snapshots: creates snapshots
- Project lifecycle → Project repositories: loads engagement
- Workspace operations → Import preview and options: requests import options
- Excel / CSV files → Import preview and options: previews source
- Import preview and options → Workspace operations: returns import choices
- Workspace operations → Background task runner: starts tasks
- Background task runner → Import and export tasks: runs task
- Import and export tasks → Excel / CSV importer: reads source
- Excel / CSV importer → Excel / CSV files: reads rows
- Import and export tasks → Project repositories: stores dataset
- Workspace operations → Sampling algorithms: performs draw
- Sampling algorithms → Sampling configuration and models: uses configuration
- Workspace operations → Project repositories: reads and saves samples
- Workspace operations → Audit event logger: records actions
- Audit event logger → Project repositories: appends events
- Project repositories → Project SQLite database: reads and writes
- Dataset and sample selection → Project repositories: loads selections
- Dataset and sample selection → Table, sidebar, dashboard, audit view: updates display
- Project SQLite database → Table, sidebar, dashboard, audit view: supplies project data
- Export controller → Project repositories: reads export data
- Export controller → Background task runner: starts export tasks
- Import and export tasks → Sample and Excel exports: writes sample Excel
- Import and export tasks → PDF and HTML reports: renders PDF or HTML
- Import and export tasks → Multi-sheet project report: writes Excel report
- Export controller → Audit event logger: records exports
- PDF and HTML reports → Report recipient: produces reports
- Sample and Excel exports → Report recipient: produces workbook
- Main window → Sampling presets: manages presets
- Main window → Application settings: saves settings
- Workspace operations → Sampling presets: loads sampling presets