# songhaotian694-oss/portal-search-app architecture

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

- Interactive diagram: https://gitdiagram.com/songhaotian694-oss/portal-search-app
- Repository: https://github.com/songhaotian694-oss/portal-search-app

## Overview

Employment Portal Search is a local desktop application for collecting employment-sharing articles, extracting structured student records, and searching or exporting those records from SQLite. The user configures an allowed portal and authenticates in an embedded browser, then starts or resumes collection and recognition; results are available through search, exploration, and export views. The graph follows documented workflow and sampled router wiring. Some UI and processing internals were not sampled, so those links rely on README statements where available.

Main entry points: [`app/api/sync.py`](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/sync.py) (Sync coordinator), [`app/main.py`](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/App.tsx) (React application), [`app/api/process.py`](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/process.py) (Recognition and extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_desktop_shell["Desktop shell<br/>[desktop_login.py]"]
  node_web_app["React application<br/>[App.tsx]"]
  node_workspace_ui["Update workspace<br/>[WorkspacePage.tsx]"]
  node_search_ui["Smart search<br/>[SearchPage.tsx]"]
  node_explore_ui["Data exploration<br/>[ExplorePage.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_collection["Portal collection"]
  node_portal_config["Portal settings<br/>[settings.py]"]
  node_auth["Browser authentication<br/>[browser_session.py]"]
  node_auth_store["Saved login state<br/>[auth_store.py]"]
  node_sync["Sync coordinator<br/>[sync.py]"]
  node_portal_api["Portal API reader<br/>[portal_api.py]"]
  node_page_adapter["Page adapter<br/>[portal_adapter.py]"]
  node_article_download["Article downloader"]
end

subgraph group_records["Local data processing"]
  node_html_parser["Article text parser<br/>[html_parser.py]"]
  node_database[("SQLite records<br/>[database.py]")]
  node_processing["Recognition and extraction<br/>[process.py]"]
  node_attachment_parser["Attachment OCR and parsing"]
  node_field_extractor["Record field extraction<br/>[field_extractor.py]"]
end

subgraph group_access["Search and results"]
  node_api_server["FastAPI application<br/>[main.py]"]
  node_search["Structured search<br/>[search.py]"]
  node_query_parser["Chinese query planner<br/>[chinese_query.py]"]
  node_analytics["Analytics<br/>[analytics.py]"]
  node_export["Excel export<br/>[export.py]"]
end

node_user(("User"))
node_portal["School portal"]

node_user -->|"launches"| node_desktop_shell
node_desktop_shell -->|"starts"| node_api_server
node_user -->|"uses"| node_web_app
node_web_app -->|"requests through"| node_api_client
node_api_client -->|"calls local API"| node_api_server
node_web_app -->|"routes to"| node_workspace_ui
node_web_app -->|"routes to"| node_search_ui
node_web_app -->|"routes to"| node_explore_ui
node_user -->|"configures"| node_portal_config
node_portal_config -->|"configures"| node_auth
node_user -->|"authenticates"| node_auth
node_auth -->|"opens login page"| node_portal
node_auth -->|"persists session"| node_auth_store
node_workspace_ui -->|"starts or resumes"| node_sync
node_sync -->|"requests records"| node_portal_api
node_sync -->|"uses page mode"| node_page_adapter
node_sync -->|"downloads articles"| node_article_download
node_article_download -->|"extracts article text"| node_html_parser
node_sync -->|"queues and checkpoints"| node_database
node_sync -->|"starts recognition"| node_processing
node_processing -->|"reads and writes records"| node_database
node_processing -->|"parses attachments"| node_attachment_parser
node_processing -->|"extracts fields"| node_field_extractor
node_user -->|"searches records"| node_search_ui
node_search_ui -->|"submits query"| node_search
node_search -->|"queries records"| node_database
node_search -.->|"plans Chinese query"| node_query_parser
node_search -->|"summarizes results"| node_analytics
node_user -->|"explores relationships"| node_explore_ui
node_explore_ui -.->|"requests data"| node_api_client
node_search_ui -->|"exports current results"| node_export
node_user -->|"exports all data"| node_export
node_export -->|"reads records"| node_database
node_api_server -->|"registers routes"| node_search
node_api_server -->|"registers routes"| node_sync
node_api_server -->|"registers routes"| node_processing
node_api_server -->|"registers routes"| node_export

click node_desktop_shell "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/desktop_login.py"
click node_web_app "https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/App.tsx"
click node_workspace_ui "https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/WorkspacePage.tsx"
click node_search_ui "https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/SearchPage.tsx"
click node_explore_ui "https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/ExplorePage.tsx"
click node_api_client "https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/services/api.ts"
click node_api_server "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/main.py"
click node_portal_config "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/settings.py"
click node_auth "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/browser_session.py"
click node_auth_store "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/auth_store.py"
click node_sync "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/sync.py"
click node_portal_api "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/portal_api.py"
click node_page_adapter "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/portal_adapter.py"
click node_article_download "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/article_downloader.py"
click node_html_parser "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/html_parser.py"
click node_database "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/database.py"
click node_processing "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/process.py"
click node_attachment_parser "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/attachment_parser.py"
click node_field_extractor "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/field_extractor.py"
click node_search "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/search.py"
click node_query_parser "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/chinese_query.py"
click node_analytics "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/analytics.py"
click node_export "https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/export.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_desktop_shell,node_web_app,node_workspace_ui,node_search_ui,node_explore_ui,node_api_client,node_user toneBlue
class node_portal_config,node_auth,node_auth_store,node_sync,node_portal_api,node_page_adapter,node_article_download toneAmber
class node_html_parser,node_database,node_processing,node_attachment_parser,node_field_extractor toneMint
class node_api_server,node_search,node_query_parser,node_analytics,node_export toneRose
class node_portal toneIndigo
```

## Components

### Desktop interface

- [Desktop shell](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/desktop_login.py): `app/desktop_login.py`
- [React application](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Update workspace](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/WorkspacePage.tsx): `frontend/src/pages/WorkspacePage.tsx`
- [Smart search](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/SearchPage.tsx): `frontend/src/pages/SearchPage.tsx`
- [Data exploration](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/pages/ExplorePage.tsx): `frontend/src/pages/ExplorePage.tsx`
- [Frontend API client](https://github.com/songhaotian694-oss/portal-search-app/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Portal collection

- [Portal settings](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/settings.py): `app/settings.py`
- [Browser authentication](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/browser_session.py): `app/crawler/browser_session.py`
- [Saved login state](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/auth_store.py): `app/crawler/auth_store.py`
- [Sync coordinator](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/sync.py): `app/api/sync.py`
- [Portal API reader](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/portal_api.py): `app/crawler/portal_api.py`
- [Page adapter](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/portal_adapter.py): `app/crawler/portal_adapter.py`
- [Article downloader](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/crawler/article_downloader.py): `app/crawler/article_downloader.py`

### Local data processing

- [Article text parser](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/html_parser.py): `app/processing/html_parser.py`
- [SQLite records](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/database.py): `app/database.py`
- [Recognition and extraction](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/process.py): `app/api/process.py`
- [Attachment OCR and parsing](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/attachment_parser.py): `app/processing/attachment_parser.py`
- [Record field extraction](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/field_extractor.py): `app/processing/field_extractor.py`

### Search and results

- [FastAPI application](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/main.py): `app/main.py`
- [Structured search](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/search.py): `app/api/search.py`
- [Chinese query planner](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/processing/chinese_query.py): `app/processing/chinese_query.py`
- [Analytics](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/analytics.py): `app/api/analytics.py`
- [Excel export](https://github.com/songhaotian694-oss/portal-search-app/blob/main/app/api/export.py): `app/api/export.py`

### Other components

- **User**
- **School portal**

## Connections

- User → Desktop shell: launches (evidence: `README.md`)
- Desktop shell → FastAPI application: starts (evidence: `launcher.py`)
- User → React application: uses (evidence: `README.md`)
- React application → Frontend API client: requests through (evidence: `frontend/src/App.tsx`)
- Frontend API client → FastAPI application: calls local API (evidence: `README.md`)
- React application → Update workspace: routes to
- React application → Smart search: routes to
- React application → Data exploration: routes to
- User → Portal settings: configures (evidence: `README.md`)
- Portal settings → Browser authentication: configures (evidence: `app/crawler/browser_session.py`)
- User → Browser authentication: authenticates (evidence: `README.md`)
- Browser authentication → School portal: opens login page (evidence: `README.md`)
- Browser authentication → Saved login state: persists session (evidence: `app/crawler/browser_session.py`)
- Update workspace → Sync coordinator: starts or resumes (evidence: `README.md`)
- Sync coordinator → Portal API reader: requests records (evidence: `app/api/sync.py`)
- Sync coordinator → Page adapter: uses page mode (evidence: `app/api/sync.py`)
- Sync coordinator → Article downloader: downloads articles (evidence: `app/api/sync.py`)
- Article downloader → Article text parser: extracts article text (evidence: `app/crawler/article_downloader.py`)
- Sync coordinator → SQLite records: queues and checkpoints (evidence: `app/api/sync.py`)
- Sync coordinator → Recognition and extraction: starts recognition (evidence: `app/api/sync.py`)
- Recognition and extraction → SQLite records: reads and writes records (evidence: `app/api/process.py`)
- Recognition and extraction → Attachment OCR and parsing: parses attachments (evidence: `app/api/process.py`)
- Recognition and extraction → Record field extraction: extracts fields (evidence: `app/api/process.py`)
- User → Smart search: searches records (evidence: `README.md`)
- Smart search → Structured search: submits query (evidence: `frontend/src/pages/SearchPage.tsx`)
- Structured search → SQLite records: queries records (evidence: `app/api/search.py`)
- Structured search → Chinese query planner: plans Chinese query
- Structured search → Analytics: summarizes results (evidence: `app/api/search.py`)
- User → Data exploration: explores relationships (evidence: `README.md`)
- Data exploration → Frontend API client: requests data
- Smart search → Excel export: exports current results (evidence: `README.md`)
- User → Excel export: exports all data (evidence: `README.md`)
- Excel export → SQLite records: reads records (evidence: `app/api/export.py`)
- FastAPI application → Structured search: registers routes (evidence: `app/main.py`)
- FastAPI application → Sync coordinator: registers routes (evidence: `app/main.py`)
- FastAPI application → Recognition and extraction: registers routes (evidence: `app/main.py`)
- FastAPI application → Excel export: registers routes (evidence: `app/main.py`)
