OMS API — an internal Order Management API. Create / track / cancel / refund orders. Customers never touch it; finance jobs, support tooling and the mobile app talk to it.
server.js — port 4790 (finance dependency — changing it = 💥)controllers/ — routes are just wiring| server.js | Express app + /health (200-always contract) |
| config.js | env fallbacks + ⚠️ hardcoded secrets |
| routes/ | 3 files — URL → controller wiring |
| controllers/ | auth · users · orders (pricing engine ⭐) |
| db/connection.js | pool + FAKE_MODE in-memory stubs |
| utils/ | helpers (dead code) + logger (frozen format) |
| legacy/ | v1 schema — do not drop ⚠️ |
| docs/ | 2019 doc — 8 lies, replaced by this kit |
flowchart LR
C[Clients] -->|HTTP 4790| S[server.js]
S --> M[Middleware]
M --> AR[authRoutes]
M --> UR[userRoutes]
M --> OR[orderRoutes]
AR --> AC[authController]
UR --> UC[userController]
OR --> OC[orderController]
AC --> DB[(db connection)]
UC --> DB
OC --> DB
DB --> PG[(PostgreSQL)]
AC --> L[app.log]
OC --> L
UC --> L
flowchart TD
SRV[server.js]:::med
CFG[config.js]:::med
DB[(db connection)]:::high
AR[authRoutes]:::low
UR[userRoutes]:::low
OR[orderRoutes]:::low
AC[authController]:::high
UC[userController]:::med
OC[orderController]:::crit
H[helpers.js]:::med
LG[logger.js]:::low
SRV --> AR
SRV --> UR
SRV --> OR
SRV --> CFG
SRV --> LG
SRV --> DB
SRV --> AC
AR --> AC
UR --> UC
OR --> OC
AC --> DB
AC --> CFG
AC --> LG
UC --> DB
UC --> CFG
UC --> LG
UC --> AC
UC --> H
OC --> DB
OC --> CFG
OC --> LG
OC --> H
DB --> CFG
LG --> CFG
classDef crit fill:#da1e28,color:#fff
classDef high fill:#ff832b,color:#000
classDef med fill:#f1c21b,color:#000
classDef low fill:#42be65,color:#000
sequenceDiagram
autonumber
participant Cl as Client
participant Ex as Express server
participant Au as requireAuth
participant OC as orderController
participant PR as calculatePricing
participant DB as db-connection
participant PG as PostgreSQL
Cl->>Ex: POST /orders with token header
Ex->>Au: requireAuth middleware
Au->>Au: validate token and expiry
alt token invalid or expired
Au-->>Cl: 401 invalid or expired token
else token valid
Au->>Ex: attach user and role to request
end
Ex->>OC: createOrder
OC->>OC: validate items fields
alt validation fails
OC-->>Cl: 400 items missing
else items ok
OC->>PR: calculatePricing items coupon
PR->>PR: qty tiers coupons tax shipping floor
PR-->>OC: pricing breakdown object
alt FAKE MODE active
OC->>DB: fake insert in memory
DB-->>OC: fake order object
OC-->>Cl: 201 order fakeMode true
else real DB path
OC->>DB: pool connect and insert
DB->>PG: SQL insert orders
PG-->>DB: row inserted
DB-->>OC: order row
OC-->>Cl: 201 order created
end
end
erDiagram
USERS ||--o{ ORDERS : places
USERS {
int id PK
varchar login
varchar pwd_hash
varchar full_name
varchar dept
boolean is_active
int points
}
ORDERS {
int id PK
int user_id FK
jsonb items_json
int total_cents
varchar status
timestamp created_on
}
stateDiagram-v2
[*] --> P: order created
P --> C: confirmed
P --> X: cancelled
C --> X: cancelled
C --> R: refunded
X --> [*]
R --> [*]
| File | Risk | Score | Core issue |
|---|---|---|---|
| controllers/orderController.js | CRITICAL | 8/10 | 300+ line pricing engine — tiers, coupons, tax, shipping, penny rule — documented only in comments. |
| docs/API_DOCS_v2019.md | HIGH | 7/10 | "The lie table" — 8 confirmed conflicts with code. The biggest onboarding trap. |
| controllers/userController.js | MEDIUM | 6/10 | Soft-delete semantics + auth coupling. Hard delete breaks finance joins. |
| utils/helpers.js | MEDIUM | 4/10 | Dead code (formatPhoneE164 deprecated) + duplicate date formatters. |
| server.js | LOW | 3/10 | /health 200-always contract — monitoring depends on it. |
| utils/logger.js | LOW | 2/10 | Format frozen — ops grep scripts depend on it. |
See RISK-REPORT.md for config.js and db/connection.js scores.
Click the checkboxes — feels like assignment, right? 😄
Move hardcoded staging DB URL and TOKEN_SALT into environment variables. Defaults stay the same.
Add a role check on the status-change endpoint so a regular user cannot confirm/cancel arbitrary orders.
Remove dead functions like formatPhoneE164 (deprecated) and consolidate the duplicate date formatters.
grep -rn. Some "dead" functions come back from merge conflicts.| POST /auth/login | returns token (72h TTL) |
| POST /orders | pricing engine ⭐ |
| PATCH /orders/:id/status | needs role guard |
| POST /orders/:id/refund | R status (docs never knew) |
| GET /health · /status | monitoring endpoints |