System Architecture

Deployment topology, technology stack, security considerations, and operational procedures for the MICRO platform.

1. System Overview

MICRO is a self-contained, single-process Flask web application. It requires no external database, message queue, or microservice infrastructure. All instrument and specimen data is loaded from JSON files at startup into in-memory registries for fast access.

Architecture style: Monolithic with clean module boundaries
Persistence: File-based (JSON), localStorage for client-side state
Rendering: Server-side NumPy/Pillow image generation, client-side display
Communication: HTTP REST API with JSON payloads

2. Deployment Topology

Local Development

Browser ──HTTP──▶ Flask Dev Server (port 5001)
                    ├── InstrumentRegistry (in-memory)
                    ├── SpecimenRegistry   (in-memory)
                    ├── PhantomRegistry    (in-memory)
                    ├── MicroscopeSimulator
                    ├── ImagingSimulator
                    └── Static Files (CSS, JS)

Production Architecture

Browser ──HTTPS──▶ Nginx (reverse proxy)
                      ├── SSL termination
                      └──▶ Gunicorn (N workers)
                            └──▶ Flask App
                                  ├── Registries
                                  ├── Simulators
                                  └── File System (data/)

Network Configuration

Port	Service	Binding
5001	Flask development server	localhost
80	HTTP (production, redirect to HTTPS)	0.0.0.0
443	HTTPS (production via Nginx)	0.0.0.0

3. Technology Stack

Backend

Python 3.12 — Core runtime
Flask 3.1.3 — Web framework
NumPy 2.4.3 — Array operations
SciPy 1.17.1 — Scientific computing
Pillow 12.1.1 — Image processing
OpenAI 2.28.0 — AI image API

Frontend

Jinja2 — Server-side templates
Vanilla JavaScript — No framework
Font Awesome 6.5.1 — Icon set
CSS3 Custom Properties — Design system
Fetch API — AJAX requests
LocalStorage — Client persistence

Infrastructure

Windows / Linux — Cross-platform
Python venv — Isolated deps
Gunicorn — Production WSGI (Linux)
Nginx — Reverse proxy (production)

4. Security Architecture

Security Controls

Control	Implementation
Input Validation	All API inputs validated and type-checked before processing. Numeric parameters bounded to safe ranges.
Output Encoding	Jinja2 auto-escaping enabled for all HTML output. JSON responses properly encoded.
Session Security	Flask secret key generated from `os.urandom(32)`. Session cookies HttpOnly by default.
CSRF Protection	Render API uses POST with JSON body (not form-encoded). State-changing actions require explicit API calls.
File Access	Only predefined data directories (instruments, specimens, phantoms) are read. No arbitrary file access.
Error Handling	Production errors return generic messages. Debug mode only enabled in development.

Password Security

Passwords hashed with bcrypt (work factor 12)
No plain text storage — only hashes persisted
Minimum 8-character password requirement
Timing-safe comparison for authentication

5. Data Flow

Request / Response Flow

CLIENT                           SERVER
──────                           ──────
POST /api/render/microscope
  { instrument, specimen,    ──▶  Flask route handler
    magnification, stain }        │
                                  ├─ Lookup instrument (registry)
                                  ├─ Lookup specimen (registry)
                                  ├─ Check ImageLibrary for AI image
                                  │   ├─ Found: apply viewport/focus
                                  │   └─ Not found: procedural render
                                  ├─ Apply brightness/contrast
                                  ├─ Encode as PNG (Pillow)
                                  └─ Return base64 JSON
  ◀── { image, info }

Startup Sequence

create_app() — Initialize Flask application
Load InstrumentRegistry — Parse all JSON files in data/instruments/
Load SpecimenRegistry — Parse specimens from data/specimens/
Load PhantomRegistry — Parse phantoms from data/phantoms/
Create MicroscopeSimulator and ImagingSimulator instances
Register page routes and API routes
Start Flask development server on port 5001

6. Scalability

Current Capacity

Instruments: 58 loaded in memory (~200KB)
Rendering: ~100-200ms per image (512×512 procedural)
Concurrent users: Limited by Gunicorn worker count (development: single-threaded)

Scaling Options

Approach	Benefit	Complexity
Gunicorn workers	Multi-core utilisation	Low — configuration only
Image caching	Avoid re-rendering identical requests	Medium — hash-based cache
CDN for AI images	Offload generated image serving	Medium — S3/CloudFront
Async rendering	Non-blocking image generation	High — Celery/Redis