HVHoai Vi
Home / Architecture

System design

A pragmatic architecture built around operational constraints.

The system works with today’s file-based reality while creating clean boundaries for future ERP and banking APIs.

SalesFlow production architecture system map
Operational sources → Python business logic → reporting servicesSame rules for dashboard and Power BI

Data pipeline

Six layers, one source of business logic

The operational dashboard and Power BI do not invent separate formulas. Both consume outputs derived from the same Python rules.

1 · Source systems
Supplier DMSMISA salesMISA cash/bankACB statementsGoogle SheetsSell-in workbooksInventory reports
2 · Raw storage
data/purchase_files/2025_analyst/Replace-by-kind uploads
3 · Normalization
Customer codesProduct codesUnits & packsDates & monthsChannel classification
4 · Stable datasets
data_clean/*.csvClosed-month snapshotsCached reportsRace-condition locks
5 · Service layer
Assets & P&LPrice auditDelivery feesDiscount summaryExpensesExports & sync
6 · Experiences
Desktop web appMobile report viewPower BI modelExcel outputs

Reporting flow

Fast daily refresh, stable closed months

01Download full exportsKeep the user workflow simple
02Replace raw filesOne known file per source type
03Normalize current dataParse only active periods where possible
04Preserve closed monthsSnapshots remain stable
05Calculate exceptionsDebt, stock, fees, mismatches
06Publish reportsWeb dashboard and Power BI

Power BI receives a model, not a pile of source files.

The export layer currently produces 25 fact and dimension tables. It separates customer, product, channel and date dimensions from monthly P&L, inventory, cashflow, receivables, price audit and supplier fee facts.

dim_date

Shared monthly and calendar attributes.

dim_customer

Customer, channel and delivery classification.

fact_pnl_monthly

Revenue, margin, expenses, inventory and assets.

fact_receivables_monthly

Customer-month debt and collection type.

fact_inventory_movements

Sell-in, sell-out and balance movement.

fact_discount_ncc_monthly

Supplier settlement components by month.

Engineering choices

Deliberate trade-offs

A

Files before APIs

The business already has reliable exports. The architecture improves the process now without waiting for vendor API access.

B

Snapshots before databases

Closed-month CSV snapshots provide stable history with low operational overhead at current scale.

C

Plain frontend before framework

A focused HTML/CSS/JS client remains fast, portable and easy to deploy on shared hosting.

D

Cache with invalidation

Heavy Excel calculations are cached and protected with locks because multiple reports load concurrently.

E

Relative paths

The project can move between Windows, cPanel and another machine without hard-coded user directories.

F

One logic layer

The app stays authoritative; Power BI consumes exported clean tables instead of rebuilding business rules.

Architecture is useful when it makes tomorrow’s workflow easier.

Return to case study →