# mrsalehi1/askharbor architecture

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

- Interactive diagram: https://gitdiagram.com/mrsalehi1/askharbor
- Repository: https://github.com/mrsalehi1/askharbor
- Video tour (about a minute): https://gitdiagram.com/mrsalehi1/askharbor/video

## Overview

AskHarbor is a guided FAQ product: visitors choose predefined questions in an embedded widget and receive answers or follow-up choices. Site owners manage bot content, branding, websites, users, access, and backups through a panel; file mode also provides a standalone editor. The README documents both PostgreSQL-backed multi-website operation and JSON-file operation. Source evidence is sampled and incomplete, so the graph omits uncertain internal links rather than inferring them.

Main entry points: [`server/app/main.py`](https://github.com/mrsalehi1/askharbor/blob/main/server/app/main.py) (Public bot API), [`server/app/website_routes.py`](https://github.com/mrsalehi1/askharbor/blob/main/server/app/website_routes.py) (Website management), [`server/app/admin_routes.py`](https://github.com/mrsalehi1/askharbor/blob/main/server/app/admin_routes.py) (Admin management), [`server/app/auth_routes.py`](https://github.com/mrsalehi1/askharbor/blob/main/server/app/auth_routes.py) (Login and access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_visitor["Visitor experience"]
  node_widget["FAQ widget<br/>[widget.ts]"]
  node_widget_transport["Widget transport<br/>[transport.ts]"]
end

subgraph group_authoring["Content authoring"]
  node_admin_panel["Admin panel<br/>[admin-app.ts]"]
  node_admin_client["Admin API client<br/>[admin-api.ts]"]
  node_editor["Standalone editor<br/>[editor-app.ts]"]
  node_browser_rules["Browser validation<br/>[content.ts]"]
end

subgraph group_service["API and access"]
  node_public_api["Public bot API<br/>[main.py]"]
  node_origin_policy["Origin policy<br/>[cors.py]"]
  node_request_limit["Request limiting<br/>[rate_limit.py]"]
  node_website_routes["Website management<br/>[website_routes.py]"]
  node_admin_routes["Admin management<br/>[admin_routes.py]"]
  node_login_routes["Login and access<br/>[auth_routes.py]"]
  node_accounts["Account services<br/>[auth.py]"]
  node_audit["Audit log<br/>[audit.py]"]
end

subgraph group_persistence["Content and persistence"]
  node_content_rules["Content validation<br/>[content.py]"]
  node_file_content["JSON bot files"]
  node_content_storage["Content storage<br/>[storage.py]"]
  node_database[("PostgreSQL data<br/>[orm.py]")]
end

node_visitor(("Website visitor"))
node_owner(("Site owner"))
node_admin_user(("Panel user"))

node_visitor -->|"uses"| node_widget
node_widget -->|"requests data"| node_widget_transport
node_widget_transport -->|"fetches bot data"| node_public_api
node_public_api -->|"serves content"| node_content_storage
node_public_api -->|"loads in file mode"| node_file_content
node_public_api -->|"checks origins"| node_origin_policy
node_public_api -->|"limits requests"| node_request_limit
node_content_storage -->|"reads and writes"| node_database
node_content_storage -->|"validates documents"| node_content_rules
node_owner -->|"manages bots"| node_admin_panel
node_admin_panel -->|"calls"| node_admin_client
node_admin_client -->|"edits websites"| node_website_routes
node_admin_client -->|"manages accounts"| node_admin_routes
node_website_routes -->|"loads and saves"| node_content_storage
node_website_routes -->|"validates imports"| node_content_rules
node_website_routes -->|"reads and writes"| node_database
node_admin_routes -->|"manages records"| node_database
node_admin_routes -->|"checks passwords"| node_accounts
node_admin_routes -->|"records changes"| node_audit
node_admin_user -->|"signs in"| node_login_routes
node_login_routes -->|"authenticates sessions"| node_accounts
node_login_routes -->|"reads and writes sessions"| node_database
node_login_routes -->|"records events"| node_audit
node_owner -->|"edits local files"| node_editor
node_editor -->|"validates drafts"| node_browser_rules
node_editor -->|"previews conversation"| node_widget

click node_widget "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/widget.ts"
click node_widget_transport "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/transport.ts"
click node_public_api "https://github.com/mrsalehi1/askharbor/blob/main/server/app/main.py"
click node_origin_policy "https://github.com/mrsalehi1/askharbor/blob/main/server/app/cors.py"
click node_request_limit "https://github.com/mrsalehi1/askharbor/blob/main/server/app/rate_limit.py"
click node_content_rules "https://github.com/mrsalehi1/askharbor/blob/main/server/app/content.py"
click node_file_content "https://github.com/mrsalehi1/askharbor/tree/main/server/content"
click node_content_storage "https://github.com/mrsalehi1/askharbor/blob/main/server/app/storage.py"
click node_database "https://github.com/mrsalehi1/askharbor/blob/main/server/app/orm.py"
click node_admin_panel "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/admin-app.ts"
click node_admin_client "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/admin-api.ts"
click node_website_routes "https://github.com/mrsalehi1/askharbor/blob/main/server/app/website_routes.py"
click node_admin_routes "https://github.com/mrsalehi1/askharbor/blob/main/server/app/admin_routes.py"
click node_login_routes "https://github.com/mrsalehi1/askharbor/blob/main/server/app/auth_routes.py"
click node_accounts "https://github.com/mrsalehi1/askharbor/blob/main/server/app/auth.py"
click node_audit "https://github.com/mrsalehi1/askharbor/blob/main/server/app/audit.py"
click node_editor "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/editor-app.ts"
click node_browser_rules "https://github.com/mrsalehi1/askharbor/blob/main/widget/src/content.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_widget,node_widget_transport,node_admin_user toneBlue
class node_admin_panel,node_admin_client,node_editor,node_browser_rules toneAmber
class node_public_api,node_origin_policy,node_request_limit,node_website_routes,node_admin_routes,node_login_routes,node_accounts,node_audit toneMint
class node_content_rules,node_file_content,node_content_storage,node_database toneRose
class node_visitor,node_owner toneIndigo
```

## Components

### Visitor experience

- [FAQ widget](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/widget.ts): `widget/src/widget.ts`
- [Widget transport](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/transport.ts): `widget/src/transport.ts`

### Content authoring

- [Admin panel](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/admin-app.ts): `widget/src/admin-app.ts`
- [Admin API client](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/admin-api.ts): `widget/src/admin-api.ts`
- [Standalone editor](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/editor-app.ts): `widget/src/editor-app.ts`
- [Browser validation](https://github.com/mrsalehi1/askharbor/blob/main/widget/src/content.ts): `widget/src/content.ts`

### API and access

- [Public bot API](https://github.com/mrsalehi1/askharbor/blob/main/server/app/main.py): `server/app/main.py`
- [Origin policy](https://github.com/mrsalehi1/askharbor/blob/main/server/app/cors.py): `server/app/cors.py`
- [Request limiting](https://github.com/mrsalehi1/askharbor/blob/main/server/app/rate_limit.py): `server/app/rate_limit.py`
- [Website management](https://github.com/mrsalehi1/askharbor/blob/main/server/app/website_routes.py): `server/app/website_routes.py`
- [Admin management](https://github.com/mrsalehi1/askharbor/blob/main/server/app/admin_routes.py): `server/app/admin_routes.py`
- [Login and access](https://github.com/mrsalehi1/askharbor/blob/main/server/app/auth_routes.py): `server/app/auth_routes.py`
- [Account services](https://github.com/mrsalehi1/askharbor/blob/main/server/app/auth.py): `server/app/auth.py`
- [Audit log](https://github.com/mrsalehi1/askharbor/blob/main/server/app/audit.py): `server/app/audit.py`

### Content and persistence

- [Content validation](https://github.com/mrsalehi1/askharbor/blob/main/server/app/content.py): `server/app/content.py`
- [JSON bot files](https://github.com/mrsalehi1/askharbor/tree/main/server/content): `server/content`
- [Content storage](https://github.com/mrsalehi1/askharbor/blob/main/server/app/storage.py): `server/app/storage.py`
- [PostgreSQL data](https://github.com/mrsalehi1/askharbor/blob/main/server/app/orm.py): `server/app/orm.py`

### Other components

- **Website visitor**
- **Site owner**
- **Panel user**

## Connections

- Website visitor → FAQ widget: uses (evidence: `README.md`)
- FAQ widget → Widget transport: requests data (evidence: `widget/src/widget.ts`)
- Widget transport → Public bot API: fetches bot data (evidence: `README.md`)
- Public bot API → Content storage: serves content (evidence: `server/app/storage.py`)
- Public bot API → JSON bot files: loads in file mode (evidence: `README.md`)
- Public bot API → Origin policy: checks origins (evidence: `server/app/main.py`)
- Public bot API → Request limiting: limits requests (evidence: `server/app/main.py`)
- Content storage → PostgreSQL data: reads and writes (evidence: `server/app/storage.py`)
- Content storage → Content validation: validates documents (evidence: `server/app/storage.py`)
- Site owner → Admin panel: manages bots (evidence: `README.md`)
- Admin panel → Admin API client: calls (evidence: `widget/src/admin-app.ts`)
- Admin API client → Website management: edits websites (evidence: `README.md`)
- Admin API client → Admin management: manages accounts (evidence: `README.md`)
- Website management → Content storage: loads and saves (evidence: `server/app/website_routes.py`)
- Website management → Content validation: validates imports (evidence: `server/app/website_routes.py`)
- Website management → PostgreSQL data: reads and writes (evidence: `server/app/website_routes.py`)
- Admin management → PostgreSQL data: manages records (evidence: `server/app/admin_routes.py`)
- Admin management → Account services: checks passwords (evidence: `server/app/admin_routes.py`)
- Admin management → Audit log: records changes (evidence: `server/app/admin_routes.py`)
- Panel user → Login and access: signs in (evidence: `README.md`)
- Login and access → Account services: authenticates sessions (evidence: `server/app/auth_routes.py`)
- Login and access → PostgreSQL data: reads and writes sessions (evidence: `server/app/auth_routes.py`)
- Login and access → Audit log: records events (evidence: `server/app/auth_routes.py`)
- Site owner → Standalone editor: edits local files (evidence: `README.md`)
- Standalone editor → Browser validation: validates drafts (evidence: `widget/src/editor-app.ts`)
- Standalone editor → FAQ widget: previews conversation (evidence: `widget/src/editor-app.ts`)