Cell Analyzer

Modular fluorescence-imaging analysis stack combining a Next.js TypeScript frontend/API with a Python worker that runs watershed-based segmentation, Frangi filtering, and dendrite skeleton metrics.

Architecture

.
├── analysis/              # Runtime storage for uploads/results (gitignored)
├── components/            # UI components shared across pages
├── lib/                   # Node/Next helpers (paths, OpenAI client, schemas)
├── pages/                 # Next.js routes and API endpoints
├── public/                # Static assets placeholder
├── scripts/               # Environment bootstrap helpers
└── worker/                # Python analysis package

• Upload & job orchestration happens in pages/api/upload.ts. Multipart uploads are written to analysis/uploads/<jobId> and a detached Python worker process (python -m worker.cli) runs asynchronously so API requests remain responsive.
• Result retrieval lives in pages/api/results/[jobId].ts, using Zod validation to enforce schema integrity. File passthrough is exposed at /results/:jobId/* via a Next.js rewrite to pages/api/results/[jobId]/files/[...path].ts.
• Observations are generated in pages/api/observations/[jobId].ts through OpenAI Responses, turning metric payloads into narrative lab notes.
• Python worker modules under worker/ load TIFF/JPEG stacks, perform watershed segmentation and Frangi-based skeleton analysis, and emit JSON + CSV summaries together with mask/overlay artifacts.

Getting started

Prerequisites

• Node.js 18+
• Python 3.10+
• OpenAI API key (for AI observations)

Install Node dependencies

npm install

Bootstrap the Python environment

Use the provided helper for your shell:

bash scripts/bootstrap_worker.sh
# or on Windows PowerShell
pwsh scripts/bootstrap_worker.ps1

This creates worker/.venv and installs the required scientific stack (numpy, pandas, scikit-image, opencv-python-headless).

Configure environment variables

Copy the example file and add your OpenAI key:

cp .env.local.example .env.local
# Edit .env.local to add OPENAI_API_KEY

Run the development servers

In one terminal start Next.js:

npm run dev

In another terminal activate the worker virtualenv if needed for manual debugging (the API spawns it automatically for jobs):

source worker/.venv/bin/activate
python -m worker.cli --job-id demo --input analysis/uploads/demo --output analysis/results/demo

Workflow

1. Visit http://localhost:3000 and upload a folder of TIFF/JPEG images.
2. The API stores files, spawns the worker, and immediately returns a jobId.
3. Open http://localhost:3000/jobs/<jobId> to monitor. Once summary.json is produced, the UI shows metrics, download links, and an AI observation button.

Scripts

Command	Description
npm run dev	Start Next.js dev server
npm run build	Build the production bundle
npm run start	Run the compiled Next.js server
npm run worker	Execute the Python worker module manually
bash scripts/bootstrap_worker.sh	Bootstrap Python virtual environment
pwsh scripts/bootstrap_worker.ps1	Windows PowerShell equivalent

Notes

• The analysis/uploads and analysis/results directories are ignored by git to prevent leaking user data.
• Long-running processing is isolated in a detached worker so that API routes remain non-blocking.
• Zod schemas enforce the structure of summary.json before results are surfaced to the UI.