poleademo

POLEA implementation plan

This is a local, synthetic pharmacy operations demo. Telegram is deferred at the user’s request. No patient data, controlled substances, external integrations, or deployment are included.

Decisions

• Python 3.10+, FastAPI, Pydantic 2, SQLAlchemy 2, Alembic; SQLite locally and PostgreSQL in Compose.
• A same-origin, responsive HTML/CSS/JavaScript application replaces the suggested Next.js stack for this first vertical slice. All business rules and persistence live on the server.
• Immutable inventory events, transactionally maintained balances, FEFO sales, and explicit transfer approvals are the foundation.
• Demo password login uses hashed passwords and opaque server-side sessions. Production MFA and a managed identity provider remain required before live use.
• Local OCR can use Tesseract. Fixture extraction is explicitly simulated and requires review. Imports never silently infer sales from physical counts.
• Classical, reproducible forecasts and SciPy integer optimization; recommendations require separate human approval and execution.

Checklist

• Phase 0: environment, plan, commands, Compose and configuration
• Phase 1: schema/migration, authorization, event ledger, seed and invariant tests
• Phase 2: seven connected screens and receive/sale/transfer workflows
• Phase 3: Telegram deferred by user; no webhook, identity links or bot implemented
• Phase 4 first slice: safe image decoding, local/fixture OCR, physical-count review, duplicate detection, atomic/versioned adjustments
• Phase 5 first slice: three baselines, count-distribution intervals, rolling-origin backtests and visible metrics
• Phase 6 first slice: 500-path stockout/FEFO expiry simulation and labeled synthetic lead-time priors
• Phase 7 first slice: integer transfers/purchase packs/supplier orders, constraints, approval-to-draft workflow
• Phase 8 first slice: backend/browser checks, CI definition, threat model, setup and limitations

Detailed implementation and validation status is maintained here and in README.md. An unchecked production capability is not implied by a working demo.

Phase report

Phase	Main files	Verification	Limits / next work
0–1	backend/db.py, models.py, inventory.py, security.py, schemas.py, seed.py, migrations/, Makefile, Compose	migrations apply/check; invariant, concurrency, authorization and idempotency tests	one company per database; no production identity/MFA
2	frontend/, backend/main.py	seven real Chrome workflows; branded desktop/mobile screenshots reviewed; 390px layout checked	lightweight client instead of Next.js; bounded demo operational lists
3	none	explicitly deferred	build Telegram after core workflows stabilize
4	backend/documents.py, fixtures.py, frontend/assets/ledgers/	upload, duplicate, ambiguity, stale review, rollback and browser approval tests	structured physical counts only; illustrative messy fixture; no full ledger arithmetic or malware scanner
5–6	backend/intelligence.py, clock.py	reproducibility, temporal splits, imputation, expiry/transit and DST tests	no regression fitting, empirical supplier learning, calibrated coverage, hierarchy or drift monitoring
7	backend/intelligence.py, order/transfer API	MILP budget/pack/lot/safety tests; full transfer and PO receipt integration tests	deterministic expected-demand optimization; stochastic evaluation separately; no hard service guarantee or partial receipts
8	tests/, .github/workflows/check.yml, README.md, SECURITY.md, backend/verify.py	32 backend tests, 7 Chrome tests; Ruff/JS syntax/schema/dependency checks	Docker unavailable here; PostgreSQL/Redis/container runtime not executed; CI authored but not run remotely

Verification commands executed

python -m alembic upgrade head, python -m backend.fixtures, python -m backend.seed, python -m pytest -q, make check, alembic check, python -m pip check, make verify, npm run test:e2e.

One upstream Starlette warning notes its test client will migrate from httpx to httpx2. Tests pass; this is not an application failure. Runtime data, sessions, uploads, node modules and the virtual environment are ignored by Git. No secrets, hosted Site or external integration were created.

Brand and simplicity revision

• Matched poleadbs.com black/cream/gold tokens and locally served DM Sans/Fraunces fonts; reused the public logo SVG with replaceable data-logo-slot placements.
• Home: three daily actions, at most three urgent rows, and observed weekly sales trends. Activity/Settings live under More.
• Reports: recorded product history, future forecasts, suggested actions, and collapsed technical detail.
• Added /api/v1/trends from actual sale events, complete business-day windows and role/location isolation.
• Replaced decorative product copy; added docs/INTELLIGENCE.md with the actual algorithms, validation limits and proposed founder pitch.

Rodolfo’s Pharmacy presentation

• Customer-facing name: Rodolfo’s Pharmacy; demo label and “Powered by Polea” attribution.
• Single page titles; removed repeated section labels and page breadcrumbs.
• Product icons for capsules, sprays, drops, first-aid products, and other stock; icons update with product selection and appear in receipt/order confirmations.
• Searchable Help with task instructions, role-aware order guidance, and direct actions; available on mobile and via ?.
• Verified all seven existing Chrome workflows, plus desktop/mobile checks of icons, barcode selection, help search/actions, branding, and attribution. No backend accounting changes.