# Munal LMS — Stack Reference

> **Deployment update — 2026-10-12:** The production path is a supervised Python ASGI process
> plus PostgreSQL and a static React build. Docker, Redis, Celery and WeasyPrint are removed.
> PostgreSQL `expiring_state` replaces shared sessions/cache/limits, and ReportLab generates PDFs
> using bundled fonts. Follow the current README and `.env.production.example` for setup.
> Existing clinical, billing, referral, authorization and reporting calculations are retained.

> **Status:** The package tables and install commands below are the original architecture proposal, not a live dependency inventory. For current versions and installed groups, use `pyproject.toml` and `uv.lock`. The audit snapshot below records what the application currently uses.

## Current package-use audit (2026-10-04)

- **Frontend:** React 19, Vite, TanStack Query/Table, Zustand, Zod, React Hook Form, Ky, Recharts, Lucide, Sonner, React Error Boundary, DOMPurify, barcode/QR packages, Tailwind utilities, selected Radix primitives, and `@nepali-utils/core` are used. TanStack Router now handles app-wide navigation through the persistent role-aware shell. Unused date-fns and Radix Avatar, Checkbox, Scroll Area, Slot, Tabs, and Tooltip were removed.
- **Backend runtime:** FastAPI, Uvicorn/Gunicorn, SQLAlchemy/asyncpg, Alembic, Pydantic settings, python-jose, bcrypt, PostgreSQL state, ReportLab/Jinja2, Pillow, FastAPI Mail, SlowAPI, multipart upload parsing, Structlog, and conditional Sentry/Prometheus integrations are used.
- **Backend dev:** `httpx` is used by API tests; `ruff`, `pre-commit`, `mypy`, `pytest`, `pytest-asyncio`, and `types-python-jose` provide development checks/tooling.
- **Optional backend extras:** `totp` (PyOTP), `xlsx` (openpyxl), and `s3` (boto3) are future integrations with no active implementation. They are not installed by the default runtime set.
- **Not currently implemented:** PDF viewer and localization packages listed in the frontend proposal are absent from the FE manifest. `factory-boy`, Passlib, and `types-passlib` are not used. Password hashing imports `bcrypt` directly.

Keep this snapshot aligned with source imports, scripts, deployment configuration, and both package manifests when changing the stack.

---

## Frontend

**Core:** React 18 + Vite 6 + TypeScript 5

### Packages

| Package | Purpose |
|---|---|
| `@tanstack/react-query` | Server state, caching, auto-refetch, mutations |
| `@tanstack/react-router` | Type-safe file-based routing |
| `@tanstack/react-table` | Headless data tables (sortable, filterable, paginated) |
| `zustand` | Lightweight client state (auth, UI, active branch) |
| `react-hook-form` | Performant form handling (no unnecessary re-renders) |
| `@hookform/resolvers` | Connects react-hook-form with zod |
| `zod` | Schema validation (forms, API responses, env vars) |
| `ky` | Lightweight fetch wrapper (interceptors, retries, JSON) |
| `@shadcn/ui` | Accessible, composable UI component library |
| `tailwindcss` | Utility-first CSS (shadcn dependency) |
| `recharts` | Charts for dashboard analytics |
| `lucide-react` | Icon set |
| `sonner` | Toast notifications |
| `date-fns` | Date formatting & manipulation |
| `@react-pdf-viewer/core` | In-browser PDF report preview |
| `i18next` + `react-i18next` | Internationalization (Nepali / English) |

### Dev Dependencies

| Package | Purpose |
|---|---|
| `vitest` | Unit & component testing |
| `@testing-library/react` | React component test utilities |
| `eslint` + `@typescript-eslint/*` | Linting |
| `prettier` | Code formatting |

---

## Backend

**Core:** FastAPI + Python 3.12+ + Uvicorn (ASGI)

### Packages

| Package | Purpose |
|---|---|
| `fastapi` | Async API framework, auto OpenAPI docs |
| `uvicorn[standard]` | ASGI server |
| `gunicorn` | Process manager (multi-worker with uvicorn workers) |
| `sqlalchemy[asyncio]` | Async ORM (v2.0, type-annotated) |
| `asyncpg` | PostgreSQL async driver |
| `alembic` | Database migrations (auto-generate from models) |
| `pydantic` | Request/response validation, serialization (v2) |
| `pydantic-settings` | Env variable / config management |
| `python-jose[cryptography]` | JWT token creation & verification |
| `passlib[bcrypt]` | Password hashing |
| `pyotp` | OTP generation (client SMS verification) |
| PostgreSQL expiring_state | Shared sessions, revocations, OTPs, rate limits and dashboard cache |
| `reportlab` | Diagnostic and management PDF generation |
| `jinja2` | HTML templating (report PDFs, emails) |
| `openpyxl` | Excel export |
| `pillow` | Image processing (logo uploads) |
| `boto3` | S3 / MinIO file storage |
| `httpx` | Async HTTP client (SMS gateway calls) |
| `fastapi-mail` | Async email sending |
| `slowapi` | API rate limiting |
| `python-multipart` | File upload handling |
| `structlog` | Structured JSON logging |
| `sentry-sdk[fastapi]` | Error tracking |
| `prometheus-fastapi-instrumentator` | Prometheus metrics endpoint |

### Dev Dependencies

| Package | Purpose |
|---|---|
| `ruff` | Linting + formatting (replaces black, isort, flake8) |
| `mypy` | Static type checking |
| `pytest` | Test framework |
| `pytest-asyncio` | Async test support |
| `httpx` | Test client for FastAPI (also used in tests) |
| `factory-boy` | Test data factories |
| `types-passlib` | Type stubs for passlib |
| `types-python-jose` | Type stubs for python-jose |

---

## Database

| Tool | Purpose |
|---|---|
| **PostgreSQL 16** | Primary relational database |
| **PostgreSQL expiring_state** | Shared sessions, revocations, client links, OTPs, cache and rate limits |

---

## Infrastructure

| Tool | Purpose |
|---|---|
| **Gunicorn + Uvicorn** | Persistent Python ASGI process |
| **Provider HTTP proxy** | HTTPS termination and routing to the API |
| **Persistent local storage** | Uploaded signatures and files; include in backups |
| **GitHub Actions** | CI/CD (lint, test, build, deploy) |

---

## Monitoring (All Free / OSS)

| Tool | Purpose |
|---|---|
| **Structlog** | Application logging (JSON structured) |
| **Loki** | Log aggregation |
| **Prometheus** | Metrics collection (latency, errors, DB pool) |
| **Grafana** | Dashboards for logs (Loki) + metrics (Prometheus) |
| **Sentry** | Error tracking (free tier: 5K events/mo) |

---

## Install Commands

### Frontend

```bash
npx -y create-vite@latest ./ --template react-ts
npm i @tanstack/react-query @tanstack/react-router @tanstack/react-table
npm i zustand react-hook-form @hookform/resolvers zod ky
npm i recharts lucide-react sonner date-fns
npm i i18next react-i18next
npm i @react-pdf-viewer/core @react-pdf-viewer/default-layout
npx shadcn@latest init
npm i -D vitest @testing-library/react
```

### Backend

```bash
# Development (using uv):
uv sync --extra dev

# Production (using pip):
pip install -r requirements.txt
pip install --no-deps .
alembic upgrade head
bash scripts/start_production.sh
```