# uhero/udaman architecture

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

- Interactive diagram: https://gitdiagram.com/uhero/udaman
- Repository: https://github.com/uhero/udaman

## Overview

UDAMAN is a data-management and analysis application for UHERO time-series data, with separate data-portal ingestion and a Hawaii Housing Database. Users work through the Next.js interface to discover, manage, analyze, and export data; background crawlers and workers handle external data collection and scheduled processing. The README documents QPub’s scrape–parse–load workflow. Sampled source supports the MCP and OAuth flows and parts of the MLS and DCCA pipelines; other connections are limited to documented capabilities and the visible module structure.

Main entry points: [`src/core/catalog/collections/series-collection.ts`](https://github.com/uhero/udaman/blob/main/src/core/catalog/collections/series-collection.ts) (Catalog collections), [`src/core/crawlers/dcca/pipeline.ts`](https://github.com/uhero/udaman/blob/main/src/core/crawlers/dcca/pipeline.ts) (DCCA crawler), [`src/app/api/oauth/authorize/route.ts`](https://github.com/uhero/udaman/blob/main/src/app/api/oauth/authorize/route.ts) (OAuth authorization), [`src/core/crawlers/mls/pipeline.ts`](https://github.com/uhero/udaman/blob/main/src/core/crawlers/mls/pipeline.ts) (MLS crawler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Time-Series Catalog"]
  node_app["UDAMAN interface<br/>[page.tsx]"]
  node_series_ui["Series management<br/>[page.tsx]"]
  node_catalog_actions["Catalog actions<br/>[series-actions.ts]"]
  node_collections["Catalog collections"]
  node_data_store[("UDAMAN database")]
  node_analysis["Analyze and compare<br/>[page.tsx]"]
  node_exports["Downloads and exports<br/>[exports.ts]"]
end

subgraph group_ingest["Data Ingestion"]
  node_portal_ui["Data portals"]
  node_upload_actions["Portal uploads<br/>[dbedt-upload.ts]"]
  node_loader_ui["Data loaders<br/>[page.tsx]"]
  node_dcca["DCCA crawler<br/>[pipeline.ts]"]
  node_mls["MLS crawler<br/>[pipeline.ts]"]
end

subgraph group_housing["Housing Database"]
  node_hhdb_ui["Housing data tools<br/>[page.tsx]"]
  node_hhdb_data[("Housing database")]
  node_qpub["QPub processing<br/>[qpub-pipeline.ts]"]
  node_qpub_plugin["QPub scraper<br/>[service-worker.js]"]
end

subgraph group_operations["Operations and Review"]
  node_comms["Publication review<br/>[page.tsx]"]
  node_admin["Admin operations<br/>[page.tsx]"]
end

subgraph group_access["API and Access"]
  node_mcp["MCP endpoint<br/>[route.ts]"]
  node_oauth["OAuth authorization<br/>[route.ts]"]
end

node_user(("Data user"))
node_source_web(("External data sites"))
node_mcp_client(("MCP client"))
node_oauth_client(("OAuth client"))
node_qpub_site(("QPub websites"))
node_nas[("NAS files")]
node_mariadb[("Housing MariaDB")]

node_user -->|"uses"| node_app
node_app -->|"opens"| node_series_ui
node_series_ui -->|"invokes"| node_catalog_actions
node_catalog_actions -->|"queries"| node_collections
node_collections -->|"reads and writes"| node_data_store
node_user -->|"analyzes"| node_analysis
node_analysis -->|"uses series data"| node_collections
node_user -->|"requests export"| node_exports
node_exports -->|"reads export data"| node_collections
node_user -->|"selects data"| node_portal_ui
node_portal_ui -->|"submits files"| node_upload_actions
node_upload_actions -->|"records imported data"| node_collections
node_user -->|"configures loader"| node_loader_ui
node_dcca -->|"fetches profiles"| node_source_web
node_dcca -->|"caches and reads files"| node_nas
node_dcca -->|"loads projects"| node_hhdb_data
node_mls -->|"fetches listings"| node_source_web
node_mls -->|"uses cached files"| node_nas
node_user -->|"explores housing data"| node_hhdb_ui
node_hhdb_ui -->|"queries"| node_hhdb_data
node_qpub_site -->|"serves pages"| node_qpub_plugin
node_qpub_plugin -->|"saves HTML"| node_nas
node_qpub -->|"reads parsed files"| node_nas
node_qpub -->|"updates status"| node_mariadb
node_user -->|"reviews releases"| node_comms
node_user -->|"administers"| node_admin
node_mcp_client -->|"sends requests"| node_mcp
node_mcp -->|"returns responses"| node_mcp_client
node_oauth_client -->|"requests authorization"| node_oauth
node_oauth -->|"requests consent"| node_user
node_oauth -->|"redirects with result"| node_oauth_client

click node_app "https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/page.tsx"
click node_series_ui "https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/series/%5Bid%5D/page.tsx"
click node_catalog_actions "https://github.com/uhero/udaman/blob/main/src/actions/series-actions.ts"
click node_collections "https://github.com/uhero/udaman/blob/main/src/core/catalog/collections/series-collection.ts"
click node_analysis "https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/analyze/page.tsx"
click node_exports "https://github.com/uhero/udaman/blob/main/src/actions/exports.ts"
click node_portal_ui "https://github.com/uhero/udaman/blob/main/src/app/data/dbedt/components/dbedt-data-portal.tsx"
click node_upload_actions "https://github.com/uhero/udaman/blob/main/src/actions/dbedt-upload.ts"
click node_loader_ui "https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/data-loaders/new/page.tsx"
click node_dcca "https://github.com/uhero/udaman/blob/main/src/core/crawlers/dcca/pipeline.ts"
click node_mls "https://github.com/uhero/udaman/blob/main/src/core/crawlers/mls/pipeline.ts"
click node_hhdb_ui "https://github.com/uhero/udaman/blob/main/src/app/hhdb/page.tsx"
click node_hhdb_data "https://github.com/uhero/udaman/blob/main/src/core/catalog/collections/hhdb-property-collection.ts"
click node_qpub "https://github.com/uhero/udaman/blob/main/src/core/workers/processors/qpub-pipeline.ts"
click node_qpub_plugin "https://github.com/uhero/udaman/blob/main/plugins/qpub-scraper/background/service-worker.js"
click node_comms "https://github.com/uhero/udaman/blob/main/src/app/comms/page.tsx"
click node_admin "https://github.com/uhero/udaman/blob/main/src/app/admin/page.tsx"
click node_mcp "https://github.com/uhero/udaman/blob/main/src/app/api/mcp/route.ts"
click node_oauth "https://github.com/uhero/udaman/blob/main/src/app/api/oauth/authorize/route.ts"

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_series_ui,node_catalog_actions,node_collections,node_data_store,node_analysis,node_exports,node_user,node_mcp_client,node_oauth_client toneBlue
class node_portal_ui,node_upload_actions,node_loader_ui,node_dcca,node_mls,node_nas,node_mariadb toneAmber
class node_hhdb_ui,node_hhdb_data,node_qpub,node_qpub_plugin toneMint
class node_comms,node_admin toneRose
class node_mcp,node_oauth,node_source_web,node_qpub_site toneIndigo
```

## Components

### Time-Series Catalog

- [UDAMAN interface](https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/page.tsx): `src/app/udaman/[universe]/page.tsx`
- [Series management](https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/series/%5Bid%5D/page.tsx): `src/app/udaman/[universe]/series/[id]/page.tsx`
- [Catalog actions](https://github.com/uhero/udaman/blob/main/src/actions/series-actions.ts): `src/actions/series-actions.ts`
- [Catalog collections](https://github.com/uhero/udaman/blob/main/src/core/catalog/collections/series-collection.ts): `src/core/catalog/collections/series-collection.ts`
- **UDAMAN database**
- [Analyze and compare](https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/analyze/page.tsx): `src/app/udaman/[universe]/analyze/page.tsx`
- [Downloads and exports](https://github.com/uhero/udaman/blob/main/src/actions/exports.ts): `src/actions/exports.ts`

### Data Ingestion

- [Data portals](https://github.com/uhero/udaman/blob/main/src/app/data/dbedt/components/dbedt-data-portal.tsx): `src/app/data/dbedt/components/dbedt-data-portal.tsx`
- [Portal uploads](https://github.com/uhero/udaman/blob/main/src/actions/dbedt-upload.ts): `src/actions/dbedt-upload.ts`
- [Data loaders](https://github.com/uhero/udaman/blob/main/src/app/udaman/%5Buniverse%5D/data-loaders/new/page.tsx): `src/app/udaman/[universe]/data-loaders/new/page.tsx`
- [DCCA crawler](https://github.com/uhero/udaman/blob/main/src/core/crawlers/dcca/pipeline.ts): `src/core/crawlers/dcca/pipeline.ts`
- [MLS crawler](https://github.com/uhero/udaman/blob/main/src/core/crawlers/mls/pipeline.ts): `src/core/crawlers/mls/pipeline.ts`

### Housing Database

- [Housing data tools](https://github.com/uhero/udaman/blob/main/src/app/hhdb/page.tsx): `src/app/hhdb/page.tsx`
- [Housing database](https://github.com/uhero/udaman/blob/main/src/core/catalog/collections/hhdb-property-collection.ts): `src/core/catalog/collections/hhdb-property-collection.ts`
- [QPub processing](https://github.com/uhero/udaman/blob/main/src/core/workers/processors/qpub-pipeline.ts): `src/core/workers/processors/qpub-pipeline.ts`
- [QPub scraper](https://github.com/uhero/udaman/blob/main/plugins/qpub-scraper/background/service-worker.js): `plugins/qpub-scraper/background/service-worker.js`

### Operations and Review

- [Publication review](https://github.com/uhero/udaman/blob/main/src/app/comms/page.tsx): `src/app/comms/page.tsx`
- [Admin operations](https://github.com/uhero/udaman/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`

### API and Access

- [MCP endpoint](https://github.com/uhero/udaman/blob/main/src/app/api/mcp/route.ts): `src/app/api/mcp/route.ts`
- [OAuth authorization](https://github.com/uhero/udaman/blob/main/src/app/api/oauth/authorize/route.ts): `src/app/api/oauth/authorize/route.ts`

### Other components

- **Data user**
- **External data sites**
- **MCP client**
- **OAuth client**
- **QPub websites**
- **NAS files**
- **Housing MariaDB**

## Connections

- Data user → UDAMAN interface: uses
- UDAMAN interface → Series management: opens
- Series management → Catalog actions: invokes
- Catalog actions → Catalog collections: queries
- Catalog collections → UDAMAN database: reads and writes
- Data user → Analyze and compare: analyzes
- Analyze and compare → Catalog collections: uses series data
- Data user → Downloads and exports: requests export
- Downloads and exports → Catalog collections: reads export data
- Data user → Data portals: selects data
- Data portals → Portal uploads: submits files
- Portal uploads → Catalog collections: records imported data
- Data user → Data loaders: configures loader
- DCCA crawler → External data sites: fetches profiles
- DCCA crawler → NAS files: caches and reads files
- DCCA crawler → Housing database: loads projects
- MLS crawler → External data sites: fetches listings
- MLS crawler → NAS files: uses cached files
- Data user → Housing data tools: explores housing data
- Housing data tools → Housing database: queries
- QPub websites → QPub scraper: serves pages
- QPub scraper → NAS files: saves HTML
- QPub processing → NAS files: reads parsed files
- QPub processing → Housing MariaDB: updates status
- Data user → Publication review: reviews releases
- Data user → Admin operations: administers
- MCP client → MCP endpoint: sends requests
- MCP endpoint → MCP client: returns responses
- OAuth client → OAuth authorization: requests authorization
- OAuth authorization → Data user: requests consent
- OAuth authorization → OAuth client: redirects with result