384 lines
11 KiB
Markdown
384 lines
11 KiB
Markdown
# Inou - Medical Imaging Second Opinion Platform
|
|
|
|
## Vision
|
|
|
|
Patient-facing medical data platform with AI-powered second opinions. Upload your scans, connect to AI, get peace of mind.
|
|
|
|
**Target user**: Non-technical parent/spouse/caregiver who knows nothing about medical imaging but wants answers.
|
|
|
|
**Brand**: inou.com ("eye-now" - vision/seeing + immediate second opinion)
|
|
|
|
**Scope**: Human + veterinary imaging. Not just imaging - labs, vitals, supplements, genome, photos, observations.
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Service | URL |
|
|
|---------|-----|
|
|
| Portal | https://inou.com |
|
|
| Viewer | https://inou.com:8767 |
|
|
| API | https://inou.com/api/* |
|
|
|
|
| Machine | IP | Role |
|
|
|---------|-----|------|
|
|
| Ubuntu Server | 192.168.1.253 | Source, Linux builds, Production |
|
|
| Mac | local | macOS bridge builds |
|
|
| Windows | 192.168.1.9 | Windows bridge builds |
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ User │
|
|
└───────────────────────────┬─────────────────────────────────────┘
|
|
│
|
|
┌───────────────────┼───────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
|
│ Portal (443) │ │ Viewer (8767) │ │ Claude Desktop│
|
|
│ Web UI, Auth │ │ DICOM viewer │ │ + Bridge │
|
|
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
|
│ │ │
|
|
│ │ │
|
|
└───────────────────┼───────────────────┘
|
|
│
|
|
┌───────▼───────┐
|
|
│ REST API │
|
|
│ (viewer) │
|
|
└───────┬───────┘
|
|
│
|
|
┌───────▼───────┐
|
|
│ SQLite DB │
|
|
│ + Objects │
|
|
└───────────────┘
|
|
```
|
|
|
|
**Services (2 total):**
|
|
- **Portal** (443) - Web UI, authentication, proxies /api/* to viewer
|
|
- **Viewer** (8767) - DICOM viewer, REST API, image serving
|
|
|
|
### Components
|
|
|
|
| Component | Binary | Purpose |
|
|
|-----------|--------|---------|
|
|
| Portal | inou-portal | Web UI, auth, profile management, proxies API |
|
|
| Viewer | inou-viewer | DICOM viewer, REST API, image serving |
|
|
| Bridge | inou_bridge_* | Connects Claude Desktop to REST API (per-platform) |
|
|
| Lab Scrape | inou-lab-scrape | MyChart lab results scraper |
|
|
| Lab Import | inou-lab-import | Lab results importer |
|
|
| DICOM Import | import-dicom | DICOM to PNG importer |
|
|
|
|
### Bridge
|
|
|
|
The bridge connects Claude Desktop (stdio/MCP protocol) to the Inou REST API:
|
|
|
|
```
|
|
Claude Desktop → inou_bridge (stdio) → HTTPS → inou.com/api/*
|
|
```
|
|
|
|
Configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"inou": {
|
|
"command": "/Users/USERNAME/bin/inou_bridge_darwin_arm64",
|
|
"args": ["--server=https://inou.com", "--account=ACCOUNT-GUID"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The bridge translates MCP tool calls from Claude Desktop into REST API requests. There is no separate MCP server - the viewer's REST API serves all data.
|
|
|
|
---
|
|
|
|
## API Tools
|
|
|
|
Tools available via the bridge (prefixed with `inou:`):
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `list_profiles` | Show patient profiles accessible to account |
|
|
| `list_studies` | Show all studies for selected profile |
|
|
| `list_series` | Show series in a study (filter by T1, T2, AX, etc.) |
|
|
| `list_slices` | Show slices with position info |
|
|
| `fetch_image` | Get image as base64 with metadata |
|
|
| `list_lab_tests` | List available lab test names |
|
|
| `get_lab_results` | Get lab results with date range/latest filters |
|
|
| `get_version` | Check bridge/server versions |
|
|
|
|
|
|
## Database Schema
|
|
|
|
```sql
|
|
-- Core tables
|
|
patients (id, guid, name, dob, sex, created_at)
|
|
studies (id, patient_id, study_date, study_desc, folder_path)
|
|
series (id, study_id, series_number, series_desc, modality, orientation_type)
|
|
slices (id, series_id, instance_number, slice_location, orientation_type,
|
|
tr, te, png_path, rows, cols, pixel_spacing_row, pixel_spacing_col,
|
|
image_position_x/y/z, image_orientation)
|
|
|
|
-- Auth tables
|
|
accounts (id GUID, email, email_hash, name, last_login, created_at)
|
|
account_profiles (account_id, profile_id, role, email, created_at)
|
|
sessions (token, account_id, profile_id, created_at, expires_at)
|
|
auth_codes (email, code, created_at, expires_at)
|
|
|
|
-- Lab tables
|
|
lab_results (id, profile_id, test_name, value, units, ref_range_low,
|
|
ref_range_high, collected_at, source)
|
|
```
|
|
|
|
---
|
|
|
|
## Build System
|
|
|
|
All binaries built with **FIPS 140-3** cryptographic compliance (requires Go 1.24+).
|
|
|
|
### Build Flow
|
|
|
|
```
|
|
Source (.253) ──sync──► Mac ──build──► darwin binaries ──deploy──► .253
|
|
│ ▲
|
|
└────────sync──────► Win (.9) ──build──► win binaries ──deploy────┘
|
|
```
|
|
|
|
### Binaries
|
|
|
|
| Binary | Platform | Build Location |
|
|
|--------|----------|----------------|
|
|
| inou-portal | Linux | .253 |
|
|
| inou-viewer | Linux | .253 |
|
|
| import-dicom | Linux | .253 |
|
|
| inou-lab-scrape | Linux | .253 |
|
|
| inou-lab-import | Linux | .253 |
|
|
| inou_bridge_darwin_arm64 | macOS ARM | Mac |
|
|
| inou_bridge_darwin_amd64 | macOS Intel | Mac |
|
|
| inou_bridge_win_amd64.exe | Windows x64 | .9 |
|
|
| inou_bridge_win_arm64.exe | Windows ARM | .9 |
|
|
| inou_bridge_win_386.exe | Windows x86 | .9 |
|
|
|
|
### Build Commands
|
|
|
|
**Linux (on .253):**
|
|
```bash
|
|
cd ~/dev/inou
|
|
make deploy
|
|
```
|
|
|
|
**Mac bridges:**
|
|
```bash
|
|
~/dev/inou/build-mac.sh
|
|
```
|
|
|
|
**Windows bridges (from Mac):**
|
|
```bash
|
|
sshpass -p 'Helder06' ssh johan@192.168.1.9 "C:\dev\inou\build.bat"
|
|
sshpass -p 'Helder06' scp johan@192.168.1.9:'C:/dev/inou/bin/inou_bridge_win_*.exe' /tmp/
|
|
scp /tmp/inou_bridge_win_*.exe johan@192.168.1.253:/tank/inou/bin/
|
|
```
|
|
|
|
**Verify FIPS:**
|
|
```bash
|
|
ssh johan@192.168.1.253 "/tank/inou/status.sh"
|
|
```
|
|
|
|
---
|
|
|
|
## Service Management
|
|
|
|
```bash
|
|
ssh johan@192.168.1.253
|
|
/tank/inou/start.sh # Start all services
|
|
/tank/inou/stop.sh # Stop all services
|
|
/tank/inou/status.sh # Check status and FIPS compliance
|
|
```
|
|
|
|
### Logs
|
|
|
|
```bash
|
|
tail -f /tank/inou/logs/portal.log
|
|
tail -f /tank/inou/logs/viewer.log
|
|
```
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
### Source (.253)
|
|
```
|
|
~/dev/inou/
|
|
├── portal/ # Web portal + auth
|
|
├── viewer/ # DICOM viewer + REST API
|
|
├── import_dicom/ # DICOM importer
|
|
├── mcp-client/ # Bridge client source
|
|
├── scrape_mychart/ # Lab scraper + importer
|
|
├── lib/ # Shared crypto library
|
|
├── go.mod, go.sum
|
|
├── Makefile
|
|
├── README.md
|
|
├── journal.md
|
|
└── build-mac.sh
|
|
```
|
|
|
|
### Production (.253)
|
|
```
|
|
/tank/inou/
|
|
├── bin/ # All compiled binaries
|
|
├── data/inou.db # SQLite database
|
|
├── uploads/ # User uploads by GUID
|
|
├── objects/ # Converted images (GUID-based paths)
|
|
├── logs/ # Service logs
|
|
├── lang/ # Translation files
|
|
├── templates/ # Portal HTML templates
|
|
├── static/ # CSS, assets
|
|
├── static/robots.txt # Search engine rules
|
|
├── master.key # Encryption key
|
|
├── start.sh, stop.sh, status.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
### Encryption
|
|
- FIPS 140-3 compliant (Go 1.24+ native module)
|
|
- AES-256-GCM encryption at rest
|
|
- TLS 1.3 for transport
|
|
- Deterministic encryption for searchable fields
|
|
|
|
### Authentication
|
|
- Passwordless: email + one-time code (10 min expiry)
|
|
- Session cookies with configurable expiry
|
|
- Account GUID isolation (no cross-account access)
|
|
|
|
### Data Isolation
|
|
- All queries filtered by profile_id derived from session
|
|
- SQL injection protection (parameterized queries)
|
|
- Access validation on all endpoints
|
|
|
|
---
|
|
|
|
## Product Design
|
|
|
|
### Terminology
|
|
|
|
| Term | Meaning |
|
|
|------|---------|
|
|
| Account | Human with email who logs in |
|
|
| Profile | A person whose data is stored (patient) |
|
|
| Exam/Study | One imaging session |
|
|
| Series | One sequence within an exam (T1, T2, FLAIR) |
|
|
|
|
### User Flow
|
|
|
|
1. Landing page → Create account (email + code)
|
|
2. Dashboard → Add profile (name, DOB, sex)
|
|
3. Profile → Upload exam (DICOM zip)
|
|
4. Connect Claude Desktop → "Analyze my inou"
|
|
5. AI reviews images, answers questions
|
|
|
|
### Design
|
|
|
|
- Modern, warm, not clinical
|
|
- IBM Plex Sans font
|
|
- Desert color palette: warm beige (#F5EDE4), dark brown (#4A3728), terracotta (#C4704B)
|
|
|
|
### Privacy (prominent)
|
|
|
|
- Images NEVER used to train AI
|
|
- Data NEVER shared
|
|
- Always encrypted
|
|
- You own your data - delete anytime
|
|
|
|
### i18n
|
|
|
|
Languages: English, Русский, Nederlands, Español, Français, Deutsch
|
|
|
|
Detection priority: URL param → Cookie → Accept-Language → English
|
|
|
|
---
|
|
|
|
## Data Types
|
|
|
|
### Implemented
|
|
- Medical imaging (DICOM)
|
|
- Lab results
|
|
|
|
### Planned
|
|
- Medical records / clinical notes (PDF)
|
|
- Medications / prescriptions
|
|
- Genetic data (VCF files)
|
|
- Vitals (BP, HR, SpO2, weight, glucose)
|
|
- Supplements
|
|
- Symptoms / pain journal
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
### High Priority
|
|
- [ ] Position-based cross-series fetch
|
|
- [ ] find_slice_at_position tool
|
|
- [ ] Window/level controls (presets for T1, T2, FLAIR, DWI)
|
|
- [ ] Better error messages (SESSION_EXPIRED)
|
|
|
|
### Medium Priority
|
|
- [ ] Batch montage fetch
|
|
- [ ] Measurement tools (distance, area)
|
|
- [ ] Series grouping/filtering
|
|
- [ ] Report system (save markdown, PDF export)
|
|
|
|
### Lower Priority
|
|
- [ ] Expanded anatomical regions
|
|
- [ ] Report templates
|
|
- [ ] Persistent findings/annotations
|
|
|
|
### Infrastructure
|
|
- [ ] Dedicated Inou server (separate from home lab)
|
|
- [ ] Encrypted ZFS pool for PHI
|
|
- [ ] Audit logging
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### FIPS Build Fails
|
|
- Ensure Go 1.24+ installed
|
|
- Use `GOFIPS140=v1.0.0` environment variable
|
|
- FIPS requires native builds (no cross-compilation)
|
|
|
|
### Bridge Connection Issues
|
|
- Check Claude Desktop config JSON syntax
|
|
- Verify account GUID is correct
|
|
- Test API: `curl https://inou.com/api/version`
|
|
|
|
### Service Issues
|
|
```bash
|
|
# Check if running
|
|
pgrep -a inou
|
|
|
|
# Check logs
|
|
tail -100 /tank/inou/logs/portal.log
|
|
|
|
# Restart
|
|
/tank/inou/stop.sh && /tank/inou/start.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Session Log
|
|
|
|
See `journal.md` for detailed session history.
|
|
|
|
---
|
|
|
|
## Future: Unified Data Model
|
|
|
|
See `docs/DATA_MODEL_V2.md` for planned schema migration to single `observations` table.
|