Integration Document

REST API specification, external dependencies, data formats, and inter-module communication for the MICRO platform.

1. Overview

MICRO follows a monolithic-with-clean-boundaries architecture. A single Flask process serves the web UI, REST API, and simulation engines. All data is stored in JSON files on disk — no external database is required.

The platform exposes a RESTful API for programmatic access to instruments, specimens, phantoms, and rendering endpoints. All responses are JSON-encoded.

2. REST API Specification

Base URL

http://localhost:5001 (development) | Configure port in run.py

Instrument Endpoints

Method	Endpoint	Description
GET	`/api/instruments`	List all instruments. Filter with `?category=` and `?manufacturer=`
GET	`/api/search?q=`	Full-text search across instrument names and manufacturers
GET	`/api/stats`	Aggregate statistics (counts by category, manufacturer totals)

Specimen & Phantom Endpoints

Method	Endpoint	Description
GET	`/api/specimens`	List all specimen types with stains and categories
GET	`/api/phantoms`	List all anatomical phantoms with tissue layers

Rendering Endpoints

Method	Endpoint	Body Fields
POST	`/api/render/microscope`	`manufacturer_key, model_key, specimen_id, magnification, illumination, stain, focus, pan_x, pan_y, brightness, contrast`
POST	`/api/render/imaging`	`manufacturer_key, model_key, phantom_id, modality_params, pan_x, pan_y, brightness, contrast`

Response Format

Render endpoints return:

{
  "image": "<base64-encoded PNG>",
  "info": {
    "model": "...",
    "manufacturer": "...",
    ...modality-specific metadata
  }
}

3. External Dependencies

Python Packages

Package	Version	Purpose
`flask`	3.1.3	Web server framework and routing
`numpy`	2.4.3	Array operations, image pixel manipulation
`scipy`	1.17.1	Gaussian filtering, signal processing
`Pillow`	12.1.1	Image encoding (array → PNG bytes)
`openai`	2.28.0	AI image generation API client (backlogged)

Client-Side CDN Libraries

Library	Purpose
Font Awesome 6.5.1	Icon set for UI elements

Browser APIs

Fetch API — AJAX calls to REST endpoints
Canvas 2D — Image display in viewers (via <img> elements)
LocalStorage — Bug tracker persistence, user preferences

4. Data Formats

Instrument JSON Schema

{
  "manufacturer": "string",
  "model": "string",
  "category": "microscope|ct|mri|ultrasound|...",
  "type": "string (subtype)",
  "specifications": { ... category-specific },
  "imaging_modes": ["string"],
  "product_url": "string (URL)"
}

Specimen JSON Schema

{
  "id": "string",
  "name": "string",
  "category": "hematology|histology|microbiology|...",
  "stains": ["unstained", "h_and_e", "gram", ...],
  "features": { ... specimen characteristics }
}

Phantom JSON Schema

{
  "id": "string",
  "name": "string",
  "description": "string",
  "tissue_layers": [
    { "name": "string", "density": float, ... }
  ]
}

5. Deployment

Local Development Setup

python -m venv .venv — Create virtual environment
.venv\Scripts\activate — Activate (Windows)
pip install flask numpy scipy Pillow openai — Install dependencies
python run.py — Start server on port 5001
Open http://localhost:5001 in browser

Environment Variables

Variable	Purpose	Required
`OPENAI_API_KEY`	API key for AI image generation	Optional (for image generation only)

File Structure

MICRO/
├── data/
│   ├── instruments/       # 16 manufacturer JSON files
│   ├── specimens/         # 15 specimen type JSONs
│   ├── phantoms/          # 8 anatomical phantom JSONs
│   ├── image_prompts/     # AI prompt catalog
│   └── generated_images/  # AI-generated images (output)
├── micro/
│   ├── instruments/       # Registry, simulators
│   ├── specimens/         # Specimen registry
│   ├── phantoms/          # Phantom registry
│   ├── images/            # Image library
│   └── web/               # Flask server, templates, static
├── generate_images.py     # AI image generation script
└── run.py                 # Application entry point

6. Inter-Module Communication

Data Flow

Browser → Flask — HTTP request (page route or API call)
Flask → Registry — Query instruments/specimens/phantoms from in-memory index
Flask → Simulator — Pass instrument + specimen/phantom + parameters
Simulator → ImageLibrary — Check for AI-generated image (optional)
Simulator → NumPy — Procedural rendering fallback (array operations)
NumPy → Pillow — Encode array as PNG bytes
Flask → Browser — Return base64-encoded PNG in JSON response

Dependency Graph

server.py
  ├── InstrumentRegistry  ← data/instruments/*.json
  ├── SpecimenRegistry    ← data/specimens/*.json
  ├── PhantomRegistry     ← data/phantoms/*.json
  ├── MicroscopeSimulator ← ImageLibrary
  └── ImagingSimulator    ← ImageLibrary