# Saraswati — Systems Deep Dive

> The `libs/saraswati/` area: twenty-four Nx libraries that implement Oshun's
> **advanced-technology / industrial deep-tech** domain — manufacturing, energy,
> mobility, IoT, life-sciences and infrastructure intelligence across roughly
> nineteen business units, with a pronounced Ghana / West-Africa market focus.

## What this area is

Saraswati is the platform's "advanced technology" vertical: a family of domain
libraries that model real industrial engineering and operations rather than
generic CRUD. Each library owns a single deep-tech business unit (battery cells,
solar panels, EVs, pharmaceuticals, satellites, e-waste recovery, and so on) and
carries the standards, formulas, and catalogs that domain actually uses — IEC/UN
battery test sequences, IPC PCB rules, ISO 13485 / ISO 14971 medical controls,
SAE J3016 ADAS levels, Bass-diffusion adoption curves, NPV/IRR financial models,
Shannon/THz link budgets, and post-quantum-crypto migration tooling. Every
project carries the `scope:saraswati` and `type:domain` Nx tags and a uniform
`test` (`npx vitest run`) / `lint` (`eslint src/`) target pair.

The libraries split into three tiers. A **foundation tier** — `@saraswati/core`
(shared branded-ID types, Zod validators, and standards constants),
`@saraswati/db` (the Drizzle/PostgreSQL persistence layer), and
`@saraswati/gateway` (the Hono HTTP/GraphQL/MQTT API surface) — underpins
everything. A **vertical tier** of fifteen single-business-unit domain libraries
(`additive`, `battery`, `drones`, `electronics`, `ev`, `ewaste`, `fintech-hw`,
`iot`, `medical`, `pharma`, `robotics`, `satellite`, `security`, `solar`,
`telecom`) holds the domain engineering logic. A **cross-BU operational tier**
(`command`, `factory`, `fleet`, `iot-platform`, `financials`, `market-intel`)
aggregates and orchestrates across the verticals — portfolio dashboards, MES,
fleet management, device-management consoles, financial models, and market
intelligence.

A recurring marker across the area is the explicit African-market grounding:
`GHANA_GRID_EMISSION_FACTOR = 0.48 kgCO₂/kWh`, `GHANA_IRRADIANCE_MAP`,
`GHANA_APPLIANCE_CATALOG`, `GHANA_CELLULAR_PLANS`, mobile-money PAYGO
processors, Ghana FDA dossier builders (Act 851), and WHO-priority disease
multipliers for drug-discovery scoring. The domain constants are real and
region-specific, not placeholders. Many verticals also ship a `*-sota.test.ts`
suite paired with a `sota/` sub-module carrying the more advanced
(state-of-the-art) capabilities — swarm planners, surgical-robotics filters, LEO
constellation planners, quantum-safe crypto, 6G/THz tracking, zero-trust IoT.

## How it fits the wider system

The dependency flow is bottom-up within the area: vertical and operational
libraries import branded IDs, shared types, and standards from
`@saraswati/core`; `@saraswati/db` persists their entities via Drizzle (40
`pgTable` definitions over a PostGIS/TimescaleDB/pgvector schema); and
`@saraswati/gateway` composes the verticals into a single REST/GraphQL/WebSocket
surface, mounting seventeen business-unit route groups under `/api/v1/{bu}/`
behind JWT+RBAC, per-BU rate limiting, Prometheus metrics, OpenTelemetry
tracing, and circuit breakers. The cross-BU operational libraries (`command`,
`fleet`, `factory`, `iot-platform`, `financials`, `market-intel`) sit above the
verticals and read their outputs to build portfolio-level views. The matching
wire contracts live separately in `libs/contracts/saraswati` (documented in the
Contracts area), which is organised by counterpart domain; this
`libs/saraswati/` area is the implementation behind those contracts.

## Entity reference

### @saraswati/core

The shared type-and-standards substrate for the whole area
(`libs/saraswati/core/src`). Its `index.ts` barrels eight modules — `ids.ts`
(branded ID types), `vehicle.ts`, `energy.ts`, `iot.ts`, `pharma.ts`,
`robotics.ts`, `telecom.ts`, and `manufacturing.ts` — each a Zod-validated type
library tied to real standards (e.g. `energy.ts` headers IEC 62133 / UN 38.3 /
IEC 62619 and models LFP/NMC/NCA chemistries and EV/SHS application types;
`manufacturing.ts` covers e-waste, additive, security and fintech shared types).
It exists so every other Saraswati library shares one canonical set of IDs and
domain enums rather than re-declaring them. Fully implemented.

### @saraswati/db

The persistence layer (`libs/saraswati/db/src`). `schema.ts` is a Drizzle ORM
schema with ~40 `pgTable` definitions plus shared `pgEnum`s (`saraswati_status`,
`saraswati_priority`, `saraswati_quality_status`, …) for a PostgreSQL database
documented as carrying PostGIS, TimescaleDB and pgvector extensions.
`connection.ts` provides a tuned `pg` connection pool (`SARASWATI_DATABASE_URL`,
configurable max/min/idle/statement timeouts) wrapped by `drizzle()`; the barrel
also re-exports `migrations.ts`, `seed.ts`, and `cache.ts` (Redis key/TTL
definitions). It is the real data tier for the domain, not a stub — it fails
loud (`throw`) when the connection URL is unset.

### @saraswati/gateway

The HTTP/GraphQL/MQTT API gateway (`libs/saraswati/gateway/src`). `app.ts`
builds a Hono application that mounts seventeen business-unit route groups under
`/api/v1/{bu}/` (`ev`, `battery`, `solar`, `iot`, `electronics`, `pharma`,
`robotics`, `drones`, `telecom`, `medical`, `fintech-hw`, `security`, `ewaste`,
`additive`, `satellite`, `market-intel`, `financials`) behind a full middleware
chain: JWT auth + RBAC (`middleware/auth.ts`, with `ROLE_HIERARCHY` and per-BU
access), sliding-window rate limiting, Prometheus metrics, OpenTelemetry-style
tracing (`traceparent` parsing), structured logging, and circuit breakers. It
also ships a GraphQL schema+executor, an OpenAPI spec, a gRPC/proto service
surface, Kafka/CQRS scaffolding, and MQTT + WebSocket routing. Substantial, real
implementation.

### @saraswati/additive

Additive-manufacturing (3D-printing) intelligence
(`libs/saraswati/additive/src`). Barrels `fleet`, `material`, `design`, and
`applications` modules. `design/design.ts` implements DFAM optimisation
(overhang/support/orientation analysis), STL validation (non-manifold,
inverted-normal, thin-wall checks), a print-job scheduler, slicing-parameter
presets, print-time/material estimation, and post-processing/quality workflows.
Real domain logic with documented print-farm algorithms.

### @saraswati/battery

One of the largest verticals (second only to @saraswati/ev by LOC) — battery and
energy-storage intelligence (`libs/saraswati/battery/src`). Covers cell
selection/procurement (`cell/cell-catalog.ts` with a `BATTERY_CELL_CATALOG`, LFP
binning, supply-chain risk), module/pack engineering (busbar/BMS/enclosure/HV
design), quality testing against named standards (UN 38.3, IEC 62619, IEC 62660
trackers; SoH/EOL projection; EIS recording), stationary storage sizing,
second-life and recycling assessment, production planning with full genealogy
traceability, and a `next-gen/` SOTA set (solid-state, Na-ion, EU battery
passport, recycling tracker). Two test suites (`battery.test.ts`,
`battery-sota.test.ts`). Fully implemented.

### @saraswati/command

The portfolio "technology operations" command dashboard
(`libs/saraswati/command/src`), tasks 60.21.1.x. `kpi/kpi-aggregator.ts`
computes cross-BU KPIs over all nineteen business units using real formulas —
OEE = Availability × Performance × Quality (ISO 22400 / SEMI E10), weighted
portfolio revenue/margin, fleet utilisation, an alert-severity index, and CO₂
avoided using `GHANA_GRID_EMISSION_FACTOR = 0.48`. Additional modules cover
manufacturing status, supply chain, quality, financial, regulatory, and alert
dashboards. A cross-BU aggregation layer, fully implemented.

### @saraswati/drones

UAV / drone-operations intelligence (`libs/saraswati/drones/src`): fleet,
flight, agriculture, survey, delivery, and data modules plus a `sota/`
swarm-planner. `sota/swarm-planner.ts` implements multi-drone survey-coverage
planning, 3-D conflict detection, and edge-AI inference feasibility, plus a
humanoid-robot comparative scorer. Includes a
`delivery/defect-inference.spec.ts` and both `drones.test.ts` and
`drones-sota.test.ts`. Real implementation.

### @saraswati/electronics

Contract electronics manufacturing (CEM/PCBA) intelligence
(`libs/saraswati/electronics/src`). Modules: `dfm/` (DFM analysis, IPC-2221
trace widths, panelization, stackup/impedance), `smt/` (stencil, paste-print,
pick-and-place, reflow profiles, SPI/AOI, FAI), `assembly/` (through-hole, wave
& selective solder, harness, conformal coat, ESD control), `testing/` (ICT
fixtures, functional/boundary-scan, burn-in/ESS, IPC-A-610 workmanship,
counterfeit detection), `production/` (scheduler, MRP, OEE, NCR), and an `ai/`
SOTA set (quality inspector, predictive maintenance, digital twin).
`ai/predictive-maintenance.ts` does real condition monitoring — vibration RMS/
kurtosis, RUL estimation, thermal anomaly, motor-current THD. Deep, real domain.

### @saraswati/ev

Electric-vehicle platform management (`libs/saraswati/ev/src`): vehicle design,
powertrain, battery pack/BMS, chassis, certification/homologation, production,
fleet/dealer, plus SOTA `v2g/` and `autonomous/adas.ts`. `autonomous/adas.ts`
implements SAE J3016 ADAS level classification, time-to-collision risk, sensor-
suite coverage, and autonomous-fleet ROI. Two test suites (`ev.test.ts`,
`ev-sota.test.ts`). Fully implemented.

### @saraswati/ewaste

E-waste recycling and circular-economy intelligence
(`libs/saraswati/ewaste/src`): `collection`, `recovery`, `compliance`, and
`circular` modules. `recovery/recovery.ts` models precious-metal recovery
(Au/Ag/Pd/Pt/Cu) with PCB grade classification, hydro- and pyro-metallurgical
process trackers, assay/LME price lookup, and yield calculation. Real domain
logic grounded in recovery chemistry.

### saraswati-factory

Manufacturing Execution System (MES) across the verticals
(`libs/saraswati/factory/src`, package `@saraswati/factory`), tasks 60.21.3.x.
Modules: electronics MES, pharma dashboard, battery assembly, solar
manufacturing, print farm, production planning, and NCR management.
`planning/production-planning.ts` does real order-to-line allocation with
utilisation-based selection, capacity loading, and completion-date estimation
with partial remaining capacity. A cross-BU operational layer; note the Nx
project name is the non-scoped `saraswati-factory`.

### @saraswati/financials

Financial modelling for the portfolio (`libs/saraswati/financials/src`), tasks
60.19.x. `bu-models/bu-models.ts` (provides `computeIRR`) and
`portfolio/portfolio.ts` build per-BU financial models (fintech-hw, security,
e-waste, additive, satellite), consolidated P&L, cash-flow projection, NPV/IRR
scenario modelling, and sensitivity analysis — with real `computeNPV`, `pvifa`,
and IRR math against a fixed reference date. Fully implemented.

### @saraswati/fintech-hw

Fintech-hardware intelligence (`libs/saraswati/fintech-hw/src`): POS terminals,
ATMs/kiosks, biometrics, and field deployment. `pos/pos.ts` covers POS hardware
spec, connectivity, payment-method configuration (EMV/contactless/MSR/QR/mobile-
money), BOM generation, PCI-PTS and EMV L1/L2 certification tracking, and OTA
firmware management. Real domain logic with the relevant payment-industry
standards.

### saraswati-fleet

Vehicle-and-drone fleet management (`libs/saraswati/fleet/src`, package
`@saraswati/fleet`), tasks 60.21.2.x. Modules: fleet overview, EV health, drone
mission control, charging infrastructure, scheduler, analytics, and driver/pilot
performance. `analytics/fleet-analytics.ts` implements real TCO/ROI modelling
and carbon-payback calculation for EV adoption. A cross-BU operational layer; Nx
project name is the non-scoped `saraswati-fleet`.

### saraswati-iot-platform

The IoT device-management platform console (`libs/saraswati/iot-platform/src`,
package `@saraswati/iot-platform`), tasks 60.21.4.x. Modules: device registry,
device detail, smart-city ops, rule engine, OTA manager, and data export.
`rules/rule-engine.ts` implements real condition evaluation (operators, rule-set
processing, effectiveness metrics, threshold recommendation). This is the
operational management plane; the deep IoT engineering domain lives in
`@saraswati/iot`. Nx project name is the non-scoped `saraswati-iot-platform`.

### @saraswati/iot

IoT & smart-city engineering intelligence (`libs/saraswati/iot/src`), the deep
domain behind the platform console. Tasks 60.6.x: device design (smart meters,
environmental sensors with `GHANA_AQI_CHANNELS`, GPS trackers, street lights,
waste bins, agri sensors), connectivity (LoRaWAN/NB-IoT/Sigfox/cellular/mesh
with `GHANA_CELLULAR_PLANS`), platform architecture (provisioning, device
shadows, MQTT topics, time-series store), dashboards/visualisation, smart-city
applications (with `GHANA_HEALTH_ADVISORIES`), and a `sota/zero-trust.ts`. Two
test suites. Large, fully implemented.

### @saraswati/market-intel

Advanced-technology market intelligence (`libs/saraswati/market-intel/src`),
tasks 60.18.x: EV/energy markets, technology-sector markets, and
intelligence/analysis. `intelligence/intelligence.ts` uses the Bass diffusion
model for technology-adoption forecasting, plus competitor tracking, policy
monitoring, funding tracking, import/export analysis, TAM/SAM/SOM sizing, and
report generation — grounded in named African data sources (IFC, AfDB, GRA
Ghana, MoTI Ghana). Real analytical models.

### @saraswati/medical

Medical-device and health-tech intelligence (`libs/saraswati/medical/src`):
design control (ISO 13485, ISO 14971 risk, IEC 62366 usability),
biocompatibility (ISO 10993), regulatory (multi-market registration, Ghana FDA
Act 851, EU MDR 2017/745 CE marking, FDA 510(k), UDI), quality
(QMS/CAPA/audits), and post-market surveillance/vigilance.
`regulatory/regulatory.ts` builds real multi-market registration strategies
against those named standards. Fully implemented.

### @saraswati/pharma

Pharmaceutical manufacturing intelligence (`libs/saraswati/pharma/src`), tasks
60.8.x: GMP/facility management, formulation development, batch manufacturing,
quality control, regulatory compliance, plus a SOTA
`discovery/drug-discovery.ts`. The drug-discovery tracker scores local African
manufacturing opportunities with a documented weighted formula (demand 0.30 +
precursor 0.25 + manufacturability 0.20 + regulatory 0.15 + market 0.10) and a
WHO-priority disease multiplier (1.20×, capped at 100). Two test suites. Fully
implemented.

### @saraswati/robotics

Robotics-systems intelligence (`libs/saraswati/robotics/src`): household,
construction, waste-sorting, and core robotics, plus SOTA `sota/surgical.ts` and
`sota/swarm.ts`. `sota/surgical.ts` implements evidence-based assessments —
tremor attenuation via a 2nd-order Butterworth high-pass frequency response,
placement-precision statistics (mean/std/95% bound, sub-millimetre check), and
FDA Class I/II/III pathway determination. Two test suites. Real engineering
math.

### @saraswati/satellite

Satellite & communications intelligence (`libs/saraswati/satellite/src`): VSAT
terminal management, ground-station/network, service/compliance, and a
`sota/leo-planner.ts`. The LEO planner models elevation-angle geometry,
constellation selection against latency/throughput/coverage requirements (with a
real `LEO_CONSTELLATIONS` catalog including Starlink), and link budgets. Two
test suites. Real orbital/link-budget logic.

### @saraswati/security

Security-systems intelligence (`libs/saraswati/security/src`): CCTV system
design (60.14.1.x), access control & alarms (60.14.2.x), advanced analytics &
integration (60.14.3.x), and a SOTA pair `sota/quantum-safe.ts` and
`sota/blockchain-provenance.ts`. `sota/quantum-safe.ts` provides post-quantum
crypto assessment — PQC vs classical algorithm comparison (key-size/latency
ratios), quantum-threat "Q-Day" timelines, and migration-risk/urgency
recommendations. Two test suites. Real PQC tooling.

### @saraswati/solar

Solar manufacturing and deployment intelligence (`libs/saraswati/solar/src`),
tasks 60.5.x: panel manufacturing (cell sort, string solder, lamination, EL
imaging, flash test, thin-film stacks), SHS design (`GHANA_APPLIANCE_CATALOG`,
`GHANA_PEAK_SUN_HOURS`), quality testing (IEC 61215 / IEC 61730 sequences,
degradation models), solar-resource assessment (`GHANA_IRRADIANCE_MAP` with
per-region GHI/DNI/DHI, optimal-tilt for Ghana latitudes, annual-yield
estimation), installation/maintenance, and PAYGO/warranty (mobile-money
processors, credit scoring). Large, fully implemented vertical.

### @saraswati/telecom

Telecom-infrastructure intelligence (`libs/saraswati/telecom/src`):
construction, equipment, site, maintenance, and network modules, plus a SOTA
`sota/6g-tracker.ts`. The 6G tracker models research milestones with TRL-gap
progress assessment, THz link capacity (path loss, Rx power, SNR, Gbps), Shannon
capacity, and base-station placement. Two test suites. Real RF/link-budget
logic.