How kimtrangctin03/network-quotation works
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: main.py Main app · quote_engine.py Quote engine · survey.py Survey · topology.py Topology
Components 25
Application
FastAPI app, browser pages, and request-time orchestration
- Main app · Central application wiring for routes, pages, auth, and orchestration
app/main.py - Dashboard · Primary landing page for quote workflows
app/pages/dashboard.py - Survey · Collects site and topology inputs
app/pages/survey.py - Topology · Network topology visualization and export flow
app/pages/topology.py - Quote · Quote review and saved quote workflow
app/pages/quote.py - Model quote · On-demand quotation from selected device models
app/pages/model_quote.py - Pricing UI · Pricing maintenance and review workflow
app/pages/pricing.py
Domain Logic
Core quotation, recommendation, and document generation engines
- Requirements · Derives requirements from survey inputs
app/requirement_engine.py - Recommend · Maps requirements to device model recommendations
app/recommendation_engine.py - Catalog engine · Normalizes device and catalog data for downstream use
app/catalog_engine.py - Manual entry · Supports direct part-number and device list quoting
app/manual_device_engine.py - Quote engine · Builds quote totals from selected parts and models
app/quote_engine.py - BOM engine · Generates BOM outputs and Excel exports
app/bom_engine.py
Pricing
Pricing data, rules, and persistence boundary
- Pricing engine · Coordinates price lookup and selection logic
app/pricing_engine.py - Price catalog · Retrieves pricing reference data
app/pricing/catalog.py - Price rules · Applies AM-over-list pricing selection
app/pricing/rules.py - Price storage · Stores AM prices, list prices, and pricing state
app/pricing/storage.py
Reference Data
Excel inputs and static catalog sources
- BOM spreadsheet · Representative product-family BOM input spreadsheet
data/BOM/C9200.xlsx - Device specs · Device technical specifications spreadsheet
data/Devices Specs.xlsx - Topology icons · Representative topology icon assets used for rendering
icon-library/project-topology-icons/README.md
Operations
Auth, sessions, admin workflows, and support tooling
- Auth page · Login and account access UI
app/pages/auth.py - Auth core · Server-side authentication and role handling
app/auth.py - PostgreSQL · Durable store for users, sessions, pricing overrides, logs, quotes, vendors, and settings
- localStorage · Transient survey, quote, and topology state in the browser
- Validate system · Catalog and price completeness validation tool
scripts/validate_system.py
Connections 29
- 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