Skip to content

CLAUDE.md

Latest commit

 

History

History
133 lines (97 loc) · 4.57 KB

CLAUDE.md

File metadata and controls

133 lines (97 loc) · 4.57 KB

VCell - Virtual Cell Project

Computational cell biology simulation platform (since 1997). Java monorepo with Python and TypeScript components, deployed on Kubernetes.

Repo: git@github.com:virtualcell/vcell.git License: MIT Main branch: master

Build & Test

# Full build (skip tests)
mvn clean install -DskipTests

# Fast unit tests only
mvn test -Dgroups="Fast"

# Quarkus REST service tests (uses testcontainers - needs Docker running)
mvn test -pl vcell-rest

# Build specific module with dependencies
mvn compile test-compile -pl vcell-rest -am

Java: 17 Maven: 3.8+ Quarkus: 3.5.2 (vcell-rest, vcell-server)

Module Structure

Module Purpose
vcell-core Core simulation logic, VCML model representation
vcell-math Mathematical model utilities
vcell-rest Quarkus REST API service (the main deployed API)
vcell-restclient Auto-generated Java API client
vcell-server Server-side business logic
vcell-api Legacy REST API (Restlet-based, /api/v0/)
vcell-api-types Shared API type definitions
vcell-apiclient Legacy API client
vcell-client Desktop/standalone Java client
vcell-cli Command-line interface
vcell-admin Administration tools
vcell-util Shared utilities
vcell-vmicro Virtual microscopy

OpenAPI Client Generation

OpenAPI spec is generated by Quarkus SmallRye OpenAPI from vcell-rest and stored in tools/openapi.yaml. Three clients are auto-generated:

cd tools
./generate.sh   # Generates Java, Python, and TypeScript-Angular clients
  • Java client: vcell-restclient/ (OpenAPI Generator v7.1.0)
  • Python client: python-restclient/
  • Angular client: webapp-ng/src/app/core/modules/openapi/

After regenerating clients, always verify downstream compilation:

mvn compile test-compile -pl vcell-rest -am

vcell-rest (Quarkus API)

Config: vcell-rest/src/main/resources/application.properties

  • Port: 9000 (dev), 80 (deployed)
  • Auth: OIDC via Auth0 (prod/dev), Keycloak devservices (test)
  • Databases: Oracle (prod), PostgreSQL (dev/test via testcontainers)
  • OpenAPI: SmallRye OpenAPI at /openapi, Swagger UI at /q/swagger-ui/
  • Tests: @QuarkusTest with Keycloak + PostgreSQL testcontainers

Key Domain Concepts

  • versionFlag — Curation/archive status of a model (Published, Archived, Current). This is NOT privacy. Privacy/access control uses GroupAccess.
  • BioModel — Primary biological model container (VCML format)
  • MathModel — Mathematical model representation
  • Simulation — A runnable simulation configuration within a model

Python Components

Python 3.10 + Poetry 1.2.2+

Package Location
vcell-cli-utils vcell-cli-utils/
python-restclient python-restclient/ (auto-generated)
vcell-opt pythonCopasiOpt/vcell-opt/
VTK integration pythonVtk/
Python utilities python-utils/
Data handling pythonData/

Frontend

Angular 17 app in webapp-ng/. Uses auto-generated OpenAPI TypeScript client.

cd webapp-ng
npm install
npm start          # Dev server
npm run build_prod # Production build

Docker & Deployment

  • Dockerfile at repo root — Ubuntu Jammy + Java 17 + Python 3.10
  • Docker Compose in docker/swarm/
  • Kubernetes configs in separate repo: vcell-fluxcd/kustomize/
    • Overlays: prod, stage, dev, remote-base, island-base
    • Ingress routes /api/v1/ → rest service, /api/v0/ → legacy api

CI/CD

GitHub Actions (.github/workflows/ci_cd.yml):

  1. CI-Build — Maven build + Docker image test
  2. CI-Test — Parallel test groups: Fast, MathGen_IT, SBML_IT, SEDML_SBML_IT, SEDML_VCML_IT, BSTS_IT, Quarkus
  3. CD — Docker push to ghcr.io on release

Validation Checklist

After major changes (especially removing/renaming user-facing features):

  • Check vcell-client/UserDocumentation/ for references to changed features. This is an ad-hoc XML format compiled into JavaHelp (in-app help) and HTML published at https://vcell.org/webstart/VCell_Tutorials/VCell_Help/index.html. Update documentation to stay consistent with code.
  • After regenerating OpenAPI clients (tools/generate.sh), compile downstream: mvn compile test-compile -pl vcell-rest -am

Conventions

  • Break changes into logically grouped commits (not one big commit)
  • Research known issues before trial-and-error config changes
  • When test output is saved to ./output.txt, analyze it with grep/read instead of rerunning tests