Project Brief

Medical Supply Chain Management Web Platform

A secure web application for managing medicine registration, manufacturer licenses, medicine units, ownership transfers, audit history, and public medicine verification.

Proposed implementation stack: React + TypeScript frontend, Node.js + TypeScript REST API, MySQL relational database, Docker, GitHub, Vercel for the frontend, and DigitalOcean for backend/database hosting. DigitalOcean is a proposed deployment choice and should be confirmed with the client, because the original requirement mentions AWS or Azure as infrastructure options.
What the Client Wants Users & Roles Core Features End-to-End Workflow Architecture Tech Stack Database Security MVP & Phase 2 Development Steps Open Questions

1. What the Client Wants

This is not a normal WordPress site or a simple CRUD dashboard. It is a custom full-stack web application.

Core Purpose

Track a medicine through its supply chain

The platform should keep a centralized record of a medicine from approved drug type and manufacturer licensing through medicine creation, pharmacy transfer, and final sale to a citizen. A citizen should be able to verify a medicine using its unique UUID.

Main Idea

One medicine, one identity

Every MedicineUnit gets a unique RFC 4122 v4 UUID and a record of ownership and transfers.

Government
→
Drug Type
→
Manufacturer License
→
Medicine Unit
→
Pharmacy
→
Citizen
→
Public Verification

2. Users and Roles

1. Government

Regulator / Super Admin

  • Register drug types.
  • Register manufacturers and pharmacies.
  • Issue production licenses.
  • Revoke licenses.
  • Extend licenses.
  • View and manage system records.
2. Manufacturer

Medicine Producer

  • View valid licenses.
  • Create MedicineUnits only under a valid license.
  • Receive a unique UUID for each unit.
  • Transfer medicine units to registered pharmacies.
  • View relevant medicine and transfer history.
3. Pharmacy

Medicine Receiver / Seller

  • Receive medicine from manufacturers.
  • View medicines currently owned by the pharmacy.
  • Transfer or sell a medicine to the final customer.
  • View transfer history for relevant units.
4. Citizen

Public Verification User

  • No login required for verification.
  • Enter a medicine UUID.
  • See medicine identity, manufacturer, status, expiry, current owner, and sanitized provenance information.
  • Read-only access.

3. Core Features

Government Module

Drug Type Management

  • Create and manage drug types.
  • Store core drug information.
  • Connect licenses to drug types.
Government Module

Participant Management

  • Register manufacturers.
  • Register pharmacies.
  • Maintain unique participant identities.
Government Module

License Management

  • Issue licenses.
  • Revoke licenses.
  • Extend license expiry dates.
  • Track who issued the license.
Manufacturer Module

Medicine Unit Creation

  • Validate manufacturer authorization.
  • Validate license status and expiry.
  • Validate drug-license relationship.
  • Generate a unique UUID.
Supply Chain

Ownership Transfer

  • Manufacturer → Pharmacy.
  • Pharmacy → Citizen / final customer.
  • Store every transfer as a historical event.
  • Enforce current-owner rules.
Public Portal

Medicine Verification

  • Public UUID search.
  • Return medicine details.
  • Show current status and expiry.
  • Show sanitized transfer history.
Security

Authentication & RBAC

  • Secure user login.
  • JWT-based authorization.
  • Government, Manufacturer, and Pharmacy permissions.
  • Ownership enforcement at API level.
Audit

Audit Trail

  • Track important system events.
  • Keep transfer records with timestamps.
  • Make provenance traceable.
Performance

Performance Targets

  • About 5,000 writes per day.
  • Peak target around 2–5 requests/sec.
  • Read API P95 < 3 sec.
  • Write API P95 < 5 sec.
  • Public verification P95 < 3 sec.
  • Dashboard load P95 < 2 sec.

4. End-to-End Business Workflow

Example: Paracetamol 500mg

  1. Government registers Paracetamol 500mg as a DrugType.
  2. ABC Pharma is registered as a Manufacturer.
  3. Government issues ABC Pharma a valid production license for this drug.
  4. ABC Pharma creates a new MedicineUnit.
  5. The system generates a unique UUID for that unit.
  6. ABC Pharma transfers the unit to XYZ Pharmacy.
  7. The transfer is saved as a TransferRecord.
  8. XYZ Pharmacy becomes the current owner.
  9. XYZ Pharmacy sells/transfers the medicine to the final customer.
  10. A Citizen enters the UUID on the public verification page.
  11. The system returns the medicine identity, status, expiry, current owner and sanitized provenance history.
Drug Registered
→
License Issued
→
Unit Created
→
Transfer to Pharmacy
→
Sold
→
Citizen Verifies UUID

5. Key Business Rules

Medicine Creation Rules

  • The manufacturer must be registered.
  • The manufacturer must have a valid license.
  • The license must not be revoked.
  • The license must not be expired.
  • The license must belong to the requested drug type.
  • The medicine UUID must be unique.

Ownership Transfer Rules

  • The caller must be the current owner.
  • The medicine must be in a transferable state.
  • The destination must meet the applicable participant rules.
  • Every successful transfer creates a historical record.
  • The current owner must update atomically with the transfer record.

License Status

A license can be Valid or Revoked, with issue and expiry dates.

Medicine Status

Expected statuses include Active Sold Expired Recalled

6. Proposed System Architecture

A clean three-tier application structure with a separate public verification flow.

Internet │ ├──────────────────────────────────────────────────────────┐ │ │ ▼ ▼ Vercel Public Verify React + TypeScript React Page │ │ └──────────────────────────────┬───────────────────────────┘ │ HTTPS / REST ▼ Node.js REST API TypeScript │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ Auth/RBAC Business Logic Audit │ │ │ └─────────────┼─────────────┘ ▼ MySQL Database │ ▼ DigitalOcean Hosting │ ┌─────────────┴─────────────┐ ▼ ▼ Backend Service Managed MySQL + Docker + Backups
Why this architecture? It keeps the frontend, application logic, and database separate. This makes the system easier to test, secure, maintain, and scale than putting the entire application into a single website or WordPress installation.

7. Proposed Technology Stack

Layer Technology Purpose
Frontend React + TypeScript Government, Manufacturer, Pharmacy dashboards and public verification UI.
UI CSS / UI component library Responsive admin dashboards, forms, tables, filters, alerts and public verification screens.
Backend Node.js + TypeScript REST API, business rules, authentication, authorization, validation and audit logic.
API REST API Core operations such as CreateDrugType, IssueLicense, RevokeLicense, ProlongLicense, CreateMedicineUnit, TransferOwnership and VerifyUnit.
Database MySQL Central source of truth for participants, drugs, licenses, medicine units and transfer records.
Authentication JWT-based auth Secure login and API authorization.
Authorization RBAC Role-based permissions for Government, Manufacturer and Pharmacy.
Container Docker Consistent local development and deployment environment.
Source Control Git + GitHub Version control, collaboration, code review and project history.
Frontend Hosting Vercel Simple deployment for the React frontend and staging environments.
Backend / Cloud DigitalOcean Run the Node.js API and production application infrastructure.
Database Hosting DigitalOcean Managed MySQL Managed relational database for production use.
Important: DigitalOcean is a proposed implementation choice. The original client requirement mentions AWS or Azure. Before production deployment, confirm that the client accepts DigitalOcean.

8. Proposed MySQL Data Model

The exact column design can be refined during technical specification, but these are the core relational entities.

Table What it stores Important relationships
participants Government, manufacturers, pharmacies and other participant identities. Referenced by licenses and ownership/transfer records.
drug_types Registered medicine/drug types. Referenced by licenses and medicine units.
licenses Manufacturer production licenses, status and dates. Linked to a manufacturer and drug type.
medicine_units Individual medicine package/unit records. Linked to drug type, manufacturer/license and current owner.
transfer_records Every ownership change with source, destination and timestamp. Linked to a medicine unit and participants.

Core relationship

DrugType → License → Manufacturer → MedicineUnit → CurrentOwner → TransferRecords

9. Core REST API

Government APIs

  • CreateDrugType
  • IssueLicense
  • RevokeLicense
  • ProlongLicense
  • Participant management endpoints.

Supply Chain APIs

  • CreateMedicineUnit
  • TransferOwnership
  • Medicine detail and history endpoints.
  • Ownership validation endpoints.

Public API

  • VerifyUnit
  • No login required.
  • Read-only response.
  • Sanitized provenance information.
  • Rate limiting required.

10. Security Requirements

Transport Security

  • HTTPS / TLS 1.2+.
  • Secure cookies or token handling where applicable.

Authentication

  • Password hashing.
  • JWT authentication.
  • Secure session/token handling.

Authorization

  • API-level RBAC.
  • Resource ownership checks.
  • Protected government operations.

Abuse Protection

  • Public verification rate limiting.
  • Input validation.
  • Request logging and monitoring.

Secrets

  • Database credentials must not be committed to GitHub.
  • Environment variables / managed secret storage.

Backups & Logs

  • Database backups.
  • Audit logs.
  • Application error logs.
  • Monitoring and alerts.

11. MVP Scope vs Phase 2

MVP

Build Now

  • Government module.
  • Manufacturer module.
  • Pharmacy module.
  • Drug type registration.
  • Participant registration.
  • License issue/revoke/extend.
  • Medicine unit creation and UUID generation.
  • Ownership transfer.
  • Transfer history.
  • Public medicine verification.
  • Authentication and RBAC.
  • Audit trail.
  • Security and performance testing.
Phase 2

Not in Current MVP

  • Doctor accounts.
  • Electronic prescriptions.
  • Prescription balance tracking.
  • IoT temperature monitoring.
  • GPS tracking.
  • SAP / ERP integrations.
  • Warehouse management integrations.
  • Native Android/iOS apps.
  • Multi-country regulatory workflows.

12. Recommended Development Steps

Step 1

Lock the Requirements

Confirm unclear business rules, especially citizen ownership, expiry behavior, recall behavior, physical medicine identification, and regulatory expectations.

Step 2

Project Setup

Set up GitHub, React, Node.js, TypeScript, MySQL, Docker, environment configuration and development standards.

Step 3

Database

Design the MySQL schema, relationships, indexes, migrations, constraints and seed data.

Step 4

Authentication & RBAC

Build secure login and API-level permissions for Government, Manufacturer and Pharmacy.

Step 5

Core APIs

Implement drug, license, medicine unit, transfer and public verification operations.

Step 6

Business Rules

Enforce license validation, current-owner checks, expiry rules, state transitions and audit records.

Step 7

Dashboards

Build Government, Manufacturer and Pharmacy interfaces with tables, forms, filters and details pages.

Step 8

Public Verification

Build the no-login UUID verification page and ensure the response exposes only allowed information.

Step 9

Testing

Unit tests, API tests, role-permission tests, ownership tests, invalid-license tests and end-to-end flows.

Step 10

Staging

Deploy frontend to Vercel and backend/database to the chosen staging environment. Run client demo and UAT.

Step 11

Security & Performance

Test rate limiting, authentication, authorization, logs, backups, database integrity and performance targets.

Step 12

Production Deployment

Move to the client-approved production infrastructure, configure HTTPS, monitoring, backups and release procedures.

13. Important Questions to Confirm with the Client

  1. Citizen ownership: Is the final citizen represented as a registered participant, or should the final sale be stored differently?
  2. Recall: How should a medicine become recalled? The status exists, but the core API list does not clearly define a recall operation.
  3. Expiry: Should medicine status automatically change to expired after the expiry date, or should it be calculated at verification time?
  4. Physical identity: Will the medicine UUID be printed as a plain code, QR code, barcode, or another identifier on the package?
  5. Regulatory scope: Is this a general supply-chain platform, or must the MVP meet specific US pharmaceutical/FDA/DSCSA compliance requirements?
  6. UI/UX: Does the client have wireframes/designs, or is the development team expected to design the dashboards and public verification screens?
  7. Deployment: Does the client require AWS/Azure, or will they approve DigitalOcean for the MVP/production environment?

14. What This Project Really Is

This project is best understood as a custom medical supply-chain management web application, not as a traditional website. Its main job is to control who can register drugs, issue or manage licenses, create medicine units, transfer ownership, preserve the chain of custody, and let the public verify a medicine by UUID.

Recommended build direction React + TypeScript → Node.js + TypeScript REST API → MySQL → Docker → GitHub, with Vercel for the frontend and DigitalOcean for backend/database hosting, subject to client approval of the deployment provider.