# kimtrangctin03/network-quotation architecture

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

- Interactive diagram: https://gitdiagram.com/kimtrangctin03/network-quotation
- Repository: https://github.com/kimtrangctin03/network-quotation

## Overview

1. **Overall shape**
   - This is a **FastAPI-based network quotation system** with a browser UI and a server-side calculation/pricing backend.
   - The application is centered in `app/main.py`, which likely wires together page routes, API endpoints, authentication, and orchestration across the domain engines.

2. **Primary user-facing flows**
   - The repo supports several distinct workflows: **survey → requirement calculation → model recommendation → quote/BOM export**, plus **on-demand model quoting** and **pricing maintenance**.
   - The main entry points exposed in the UI are the pages under `app/pages/`, especially `dashboard`, `survey`, `topology`, `recommendation`, `quote`, `model_quote`, `pricing`, and `calculation_results`.

3. **Domain computation layer**
   - The core business logic is split into dedicated engines:
     - `requirement_engine.py` computes requirements from survey inputs.
     - `recommendation_engine.py` suggests device models based on those requirements.
     - `quote_engine.py` aggregates pricing for selected parts/models.
     - `bom_engine.py` generates BOM outputs and Excel exports.
     - `manual_device_engine.py` supports manually entered device lists / part numbers.
     - `catalog_engine.py` appears to support catalog lookup and device data normalization.
   - These modules are the main boundary between UI/input handling and the actual network quotation logic.

4. **Pricing subsystem**
   - Pricing is handled as a separate subsystem under `app/pricing/` and `app/pricing_engine.py`.
   - The pricing package is split into:
     - `catalog.py` for catalog/data retrieval,
     - `rules.py` for price selection logic,
     - `storage.py` for persistence.
   - The pricing rule described in the README is important architecturally: **AM price wins when present; otherwise list price is used**.

5. **Persistent state and database boundary**
   - The application uses **PostgreSQL** as the durable system of record for operational data:
     - custom list-price entries,
     - AM prices,
     - users and sessions,
     - activity logs,
     - saved quote records,
     - vendors and system settings.
   - This means the repo has a clear split between:
     - **static reference data** from Excel files,
     - **mutable business data** in PostgreSQL.

6. **Reference data sources**
   - The main reference BOM/catalog inputs live under `data/BOM/*.xlsx`, with separate spreadsheets per product family such as `C9200`, `C9300`, `ISR1000`, `SFP`, etc.
   - `data/Devices Specs.xlsx` is another important source for device technical specs.
   - The README notes that `data/pricing.db` is legacy and no longer used, so the current pricing source of truth is PostgreSQL plus the Excel BOM inputs.

7. **Authentication and authorization**
   - `app/auth.py` and `app/pages/auth.py` indicate a dedicated authentication subsystem.
   - Roles are simple and operationally meaningful:
     - `user` for normal quotation and pricing workflows,
     - `admin` for account management, quote oversight, activity logs, and system status.
   - Sessions are persisted in the database and expire after 7 days, which makes auth state a server-managed concern rather than purely client-side.

8. **Admin and operational management**
   - Admin functionality includes viewing saved quotes, activity history, account management, and quote status transitions (`draft`, `submitted`, `approved`, `locked`).
   - This adds an operational control plane on top of the quoting workflows, not just a transactional quote generator.

9. **Topology and visualization**
   - The repo includes a topology visualization path: survey data is used to generate a network topology and export it as PNG.
   - `icon-library/project-topology-icons/` provides the visual assets used for that topology rendering.
   - In architecture terms, this is a presentation/output subsystem driven by survey/calculation results rather than a standalone drawing tool.

10. **Client-side state and interaction model**
    - The README states that some workflow state lives in the browser’s **`localStorage`**: survey data, in-progress quotes, and topology layout.
    - That means the app uses a hybrid model:
      - transient UI state in the browser,
      - durable records only when the user explicitly saves or submits.
    - This is relevant for diagrams because not every user action immediately becomes server-side persistence.

11. **Data export and document generation**
    - A major output boundary is **Excel BOM generation**, likely implemented through `openpyxl`/`pandas`.
    - The system can also create quotes from a list of part numbers and quantities “on demand,” which suggests the backend can operate both from structured survey-derived solutions and from direct itemized input.

12. **Tooling and validation**
    - `scripts/validate_system.py` is an operational validation tool for checking catalog completeness and missing prices.
    - `scripts/debug_campus_dropdown_cells.py` suggests the team also has a data-debugging utility for spreadsheet-driven UI/calculation issues.
    - These scripts are support tooling, not runtime services, but they reinforce that Excel-driven data quality is part of the architecture.

13. **Technology boundaries**
    - Runtime is **Python 3.10+** with **FastAPI/Uvicorn**.
    - The frontend is described as **plain HTML/CSS/JavaScript**, so there is no separate SPA framework or frontend build pipeline in this repo.
    - The main architectural split is therefore:
      - browser UI + localStorage,
      - FastAPI request handlers,
      - domain engines,
      - PostgreSQL persistence,
      - Excel/file-based reference data.

14. **What an architecture diagram should show**
    - A good diagram would place `app/main.py` at the center, with arrows to:
      - page modules for UI rendering,
      - domain engines for requirement/recommendation/quote/BOM/pricing logic,
      - PostgreSQL for users, sessions, pricing overrides, logs, and saved quotes,
      - Excel reference files under `data/BOM/` and `data/Devices Specs.xlsx`,
      - icon assets for topology rendering,
      - browser localStorage for transient workflow state.

Main entry points: [`app/main.py`](https://github.com/kimtrangctin03/network-quotation/blob/main/app/main.py) (Main app), [`app/quote_engine.py`](https://github.com/kimtrangctin03/network-quotation/blob/main/app/quote_engine.py) (Quote engine), [`app/pages/survey.py`](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/survey.py) (Survey), [`app/pages/topology.py`](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/topology.py) (Topology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Application"]
  node_n_main["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_n_dashboard["Dashboard<br/>UI page<br/>[dashboard.py]"]
  node_n_survey["Survey<br/>UI page<br/>[survey.py]"]
  node_n_topology["Topology<br/>UI page<br/>[topology.py]"]
  node_n_quote["Quote<br/>UI page<br/>[quote.py]"]
  node_n_model_quote["Model quote<br/>UI page<br/>[model_quote.py]"]
  node_n_pricing_page["Pricing UI<br/>UI page<br/>[pricing.py]"]
end

subgraph group_grp_domain["Domain Logic"]
  node_n_requirement{{"Requirements<br/>calculation engine"}}
  node_n_recommendation{{"Recommend<br/>selection engine"}}
  node_n_catalog_engine{{"Catalog engine<br/>catalog normalization<br/>[catalog_engine.py]"}}
  node_n_manual_device{{"Manual entry<br/>device input engine"}}
  node_n_quote_engine{{"Quote engine<br/>pricing aggregator<br/>[quote_engine.py]"}}
  node_n_bom_engine{{"BOM engine<br/>export engine<br/>[bom_engine.py]"}}
end

subgraph group_grp_pricing["Pricing"]
  node_n_pricing_engine{{"Pricing engine<br/>pricing service<br/>[pricing_engine.py]"}}
  node_n_price_catalog[("Price catalog<br/>pricing data access<br/>[catalog.py]")]
  node_n_price_rules{{"Price rules<br/>pricing policy<br/>[rules.py]"}}
  node_n_price_storage[("Price storage<br/>persistence layer<br/>[storage.py]")]
end

subgraph group_grp_data["Reference Data"]
  node_n_bom_data["BOM spreadsheet<br/>xlsx reference data<br/>[C9200.xlsx]"]
  node_n_specs["Device specs<br/>xlsx reference data<br/>[Devices Specs.xlsx]"]
  node_n_icons["Topology icons<br/>asset library<br/>[README.md]"]
end

subgraph group_grp_ops["Operations"]
  node_n_auth_ui["Auth page<br/>UI page<br/>[auth.py]"]
  node_n_auth["Auth core<br/>session auth<br/>[auth.py]"]
  node_n_postgres[("PostgreSQL<br/>system database")]
  node_n_localstorage[("localStorage<br/>browser state")]
  node_n_validate["Validate system<br/>ops script<br/>[validate_system.py]"]
end

node_n_main -->|"serves"| node_n_dashboard
node_n_main -->|"routes"| node_n_survey
node_n_main -->|"routes"| node_n_quote
node_n_main -->|"routes"| node_n_model_quote
node_n_main -->|"routes"| node_n_pricing_page
node_n_main -->|"routes"| node_n_topology
node_n_main -->|"serves"| node_n_auth_ui
node_n_auth_ui -->|"uses"| node_n_auth
node_n_auth -->|"reads/writes"| node_n_postgres
node_n_survey -->|"stores"| node_n_localstorage
node_n_survey -->|"feeds"| node_n_requirement
node_n_requirement -->|"outputs"| node_n_recommendation
node_n_recommendation -->|"feeds"| node_n_quote_engine
node_n_manual_device -->|"feeds"| node_n_quote_engine
node_n_catalog_engine -->|"reads"| node_n_bom_data
node_n_catalog_engine -->|"reads"| node_n_specs
node_n_quote_engine -->|"queries"| node_n_pricing_engine
node_n_pricing_engine -->|"applies"| node_n_price_rules
node_n_pricing_engine -->|"loads"| node_n_price_catalog
node_n_price_catalog -->|"persists via"| node_n_price_storage
node_n_price_storage -->|"reads/writes"| node_n_postgres
node_n_quote_engine -->|"exports"| node_n_bom_engine
node_n_bom_engine -->|"reads"| node_n_bom_data
node_n_topology -->|"renders with"| node_n_icons
node_n_topology -->|"reads/writes"| node_n_localstorage
node_n_quote -->|"reads/writes"| node_n_postgres
node_n_pricing_page -->|"reads/writes"| node_n_postgres
node_n_validate -.->|"checks"| node_n_bom_data
node_n_validate -.->|"checks"| node_n_price_storage

click node_n_main "https://github.com/kimtrangctin03/network-quotation/blob/main/app/main.py"
click node_n_dashboard "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/dashboard.py"
click node_n_survey "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/survey.py"
click node_n_topology "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/topology.py"
click node_n_quote "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/quote.py"
click node_n_model_quote "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/model_quote.py"
click node_n_pricing_page "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/pricing.py"
click node_n_auth_ui "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/auth.py"
click node_n_auth "https://github.com/kimtrangctin03/network-quotation/blob/main/app/auth.py"
click node_n_requirement "https://github.com/kimtrangctin03/network-quotation/blob/main/app/requirement_engine.py"
click node_n_recommendation "https://github.com/kimtrangctin03/network-quotation/blob/main/app/recommendation_engine.py"
click node_n_catalog_engine "https://github.com/kimtrangctin03/network-quotation/blob/main/app/catalog_engine.py"
click node_n_manual_device "https://github.com/kimtrangctin03/network-quotation/blob/main/app/manual_device_engine.py"
click node_n_quote_engine "https://github.com/kimtrangctin03/network-quotation/blob/main/app/quote_engine.py"
click node_n_bom_engine "https://github.com/kimtrangctin03/network-quotation/blob/main/app/bom_engine.py"
click node_n_pricing_engine "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing_engine.py"
click node_n_price_catalog "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/catalog.py"
click node_n_price_rules "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/rules.py"
click node_n_price_storage "https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/storage.py"
click node_n_bom_data "https://github.com/kimtrangctin03/network-quotation/blob/main/data/BOM/C9200.xlsx"
click node_n_specs "https://github.com/kimtrangctin03/network-quotation/blob/main/data/Devices Specs.xlsx"
click node_n_icons "https://github.com/kimtrangctin03/network-quotation/blob/main/icon-library/project-topology-icons/README.md"
click node_n_validate "https://github.com/kimtrangctin03/network-quotation/blob/main/scripts/validate_system.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_n_main,node_n_dashboard,node_n_survey,node_n_topology,node_n_quote,node_n_model_quote,node_n_pricing_page toneBlue
class node_n_requirement,node_n_recommendation,node_n_catalog_engine,node_n_manual_device,node_n_quote_engine,node_n_bom_engine toneAmber
class node_n_pricing_engine,node_n_price_catalog,node_n_price_rules,node_n_price_storage toneMint
class node_n_bom_data,node_n_specs,node_n_icons toneRose
class node_n_auth_ui,node_n_auth,node_n_postgres,node_n_localstorage,node_n_validate toneIndigo
```

## Components

### Application

FastAPI app, browser pages, and request-time orchestration

- [Main app](https://github.com/kimtrangctin03/network-quotation/blob/main/app/main.py): FastAPI entrypoint · Central application wiring for routes, pages, auth, and orchestration · `app/main.py`
- [Dashboard](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/dashboard.py): UI page · Primary landing page for quote workflows · `app/pages/dashboard.py`
- [Survey](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/survey.py): UI page · Collects site and topology inputs · `app/pages/survey.py`
- [Topology](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/topology.py): UI page · Network topology visualization and export flow · `app/pages/topology.py`
- [Quote](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/quote.py): UI page · Quote review and saved quote workflow · `app/pages/quote.py`
- [Model quote](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/model_quote.py): UI page · On-demand quotation from selected device models · `app/pages/model_quote.py`
- [Pricing UI](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/pricing.py): UI page · Pricing maintenance and review workflow · `app/pages/pricing.py`

### Domain Logic

Core quotation, recommendation, and document generation engines

- [Requirements](https://github.com/kimtrangctin03/network-quotation/blob/main/app/requirement_engine.py): calculation engine · Derives requirements from survey inputs · `app/requirement_engine.py`
- [Recommend](https://github.com/kimtrangctin03/network-quotation/blob/main/app/recommendation_engine.py): selection engine · Maps requirements to device model recommendations · `app/recommendation_engine.py`
- [Catalog engine](https://github.com/kimtrangctin03/network-quotation/blob/main/app/catalog_engine.py): catalog normalization · Normalizes device and catalog data for downstream use · `app/catalog_engine.py`
- [Manual entry](https://github.com/kimtrangctin03/network-quotation/blob/main/app/manual_device_engine.py): device input engine · Supports direct part-number and device list quoting · `app/manual_device_engine.py`
- [Quote engine](https://github.com/kimtrangctin03/network-quotation/blob/main/app/quote_engine.py): pricing aggregator · Builds quote totals from selected parts and models · `app/quote_engine.py`
- [BOM engine](https://github.com/kimtrangctin03/network-quotation/blob/main/app/bom_engine.py): export engine · Generates BOM outputs and Excel exports · `app/bom_engine.py`

### Pricing

Pricing data, rules, and persistence boundary

- [Pricing engine](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing_engine.py): pricing service · Coordinates price lookup and selection logic · `app/pricing_engine.py`
- [Price catalog](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/catalog.py): pricing data access · Retrieves pricing reference data · `app/pricing/catalog.py`
- [Price rules](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/rules.py): pricing policy · Applies AM-over-list pricing selection · `app/pricing/rules.py`
- [Price storage](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pricing/storage.py): persistence layer · Stores AM prices, list prices, and pricing state · `app/pricing/storage.py`

### Reference Data

Excel inputs and static catalog sources

- [BOM spreadsheet](https://github.com/kimtrangctin03/network-quotation/blob/main/data/BOM/C9200.xlsx): xlsx reference data · Representative product-family BOM input spreadsheet · `data/BOM/C9200.xlsx`
- [Device specs](https://github.com/kimtrangctin03/network-quotation/blob/HEAD/data/Devices%20Specs.xlsx): xlsx reference data · Device technical specifications spreadsheet · `data/Devices Specs.xlsx`
- [Topology icons](https://github.com/kimtrangctin03/network-quotation/blob/main/icon-library/project-topology-icons/README.md): asset library · Representative topology icon assets used for rendering · `icon-library/project-topology-icons/README.md`

### Operations

Auth, sessions, admin workflows, and support tooling

- [Auth page](https://github.com/kimtrangctin03/network-quotation/blob/main/app/pages/auth.py): UI page · Login and account access UI · `app/pages/auth.py`
- [Auth core](https://github.com/kimtrangctin03/network-quotation/blob/main/app/auth.py): session auth · Server-side authentication and role handling · `app/auth.py`
- **PostgreSQL**: system database · Durable store for users, sessions, pricing overrides, logs, quotes, vendors, and settings
- **localStorage**: browser state · Transient survey, quote, and topology state in the browser
- [Validate system](https://github.com/kimtrangctin03/network-quotation/blob/main/scripts/validate_system.py): ops script · Catalog and price completeness validation tool · `scripts/validate_system.py`

## Connections

- Main app → Dashboard: serves · Routes users into the main workflow
- Main app → Survey: routes · Loads survey entry and progression pages
- Main app → Quote: routes · Handles quote review and submission flows
- Main app → Model quote: routes · Exposes direct model quotation flow
- Main app → Pricing UI: routes · Exposes pricing maintenance workflow
- Main app → Topology: routes · Exposes topology visualization flow
- Main app → Auth page: serves · Provides authentication UI entry points
- Auth page → Auth core: uses · Delegates login and session handling
- Auth core → PostgreSQL: reads/writes · Persists users, sessions, and role state
- Survey → localStorage: stores · Keeps in-progress survey and layout state in the browser
- Survey → Requirements: feeds · Survey inputs drive requirements calculation
- Requirements → Recommend: outputs · Requirements become model selection inputs
- Recommend → Quote engine: feeds · Recommended models are priced and assembled into quotes
- Manual entry → Quote engine: feeds · Direct device lists can bypass survey-driven recommendation
- Catalog engine → BOM spreadsheet: reads · Normalizes BOM spreadsheet inputs
- Catalog engine → Device specs: reads · Uses device specification data
- Quote engine → Pricing engine: queries · Requests pricing for selected items
- Pricing engine → Price rules: applies · Selects AM price when available, otherwise list price
- Pricing engine → Price catalog: loads · Fetches pricing reference records
- Price catalog → Price storage: persists via · Uses the storage layer for pricing state
- Price storage → PostgreSQL: reads/writes · Stores pricing overrides and related business data
- Quote engine → BOM engine: exports · Produces BOM and Excel output artifacts
- BOM engine → BOM spreadsheet: reads · Builds BOM output from product-family spreadsheets
- Topology → Topology icons: renders with · Uses icon assets to draw network topology
- Topology → localStorage: reads/writes · Stores transient topology layout in the browser
- Quote → PostgreSQL: reads/writes · Loads and saves quote records and status transitions
- Pricing UI → PostgreSQL: reads/writes · Manages pricing maintenance and persisted pricing data
- Validate system → BOM spreadsheet: checks · Validates catalog completeness and reference coverage
- Validate system → Price storage: checks · Detects missing prices and data gaps
