Merge pull request #22 from Pavlopoulos-Lab/v3-fable-auto

V3 fable auto

Author: vagkaratzas

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v3]
+  pull_request:
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    defaults:
+      run: { working-directory: backend }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy app
+      - run: uv run pytest
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run: { working-directory: frontend }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm, cache-dependency-path: frontend/package-lock.json }
+      - run: npm ci
+      - run: npm run lint
+      - run: npx prettier --check src
+      - run: npx tsc -b --noEmit || npx tsc --noEmit
+      - run: npm test -- --run
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: [backend, frontend]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm, cache-dependency-path: frontend/package-lock.json }
+      - run: cd backend && uv sync && (uv run uvicorn app.main:app --port 8000 &)
+      - run: cd frontend && npm ci && npx playwright install --with-deps chromium
+      - run: cd frontend && npm run test:e2e

.gitignore

@@ -52,3 +52,4 @@ frontend/dist/
 
 # Editors
 .DS_Store
+.playwright-cli/

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        files: ^backend/
+      - id: ruff-format
+        files: ^backend/
+
+  - repo: local
+    hooks:
+      - id: eslint
+        name: eslint
+        language: system
+        entry: bash -c 'cd frontend && npx eslint src'
+        files: ^frontend/src/.*\.ts$
+        pass_filenames: false
+      - id: prettier
+        name: prettier
+        language: system
+        entry: bash -c 'cd frontend && npx prettier --check src'
+        files: ^frontend/src/
+        pass_filenames: false

.serena/project.yml

@@ -31,8 +31,12 @@ project_name: "Arena3Dweb"
 # When using multiple languages, the first language server that supports a given file will be used for that file.
 # The first language is the default language and the respective language server will be used as a fallback.
 # Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+# R dropped: legacy code being deleted through the v3 migration, and its LSP
+# (R `languageserver` package) isn't installed — its failure aborted the whole
+# language-server manager. Active dev is TS (frontend) + Python (backend).
 languages:
-- r
+- typescript
+- python
 
 # the encoding used by text files in the project
 # For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings

Arena3Dweb.Rproj

@@ -2,27 +2,20 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Active Migration
+Arena3Dweb is a web application for interactive 3D visualization of multilayered networks: **FastAPI backend** (Python, `uv`) + **Vite / TypeScript / Three.js frontend** (npm).
 
-This repository is being migrated from R/Shiny to FastAPI + Vite + TypeScript + Three.js (npm).
-
-- **`SPEC.md`** — architecture decisions, chosen stack, design patterns, API contract, and rationale. Read this first to understand why things are structured the way they are.
-- **`PLAN.md`** — phased implementation checklist with checkboxes. Check this to see what has been done and what remains before starting any work.
-- **`MIGRATION.md`** — maps each old R/Shiny file to its new equivalent; old files are deleted only after their replacement is tested.
-
-If you are on the `v3` branch, the presence of old R/Shiny files (`server.R`, `functions/`, `views/`, `www/js/`) means those pieces have not been ported yet — they are the living specification for what the new code should do.
+The app was migrated from R/Shiny to this stack. All R/Shiny source is gone; the migration history lives in:
+- **`SPEC.md`** — architecture decisions, chosen stack, design patterns, API contract, and rationale.
+- **`PLAN.md`** — phased implementation checklist (essentially complete).
+- **`MIGRATION.md`** — old R/Shiny file → new equivalent map (all rows done).
 
 ## Running the App
 
-### v3 (FastAPI + Vite — active development, `v3` branch)
-
-**Backend:**
+**Backend** (package management via `uv` — no manual venv/pip):
 ```bash
 cd backend
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-uvicorn app.main:app --reload   # http://localhost:8000
+uv sync                                  # installs deps + dev group into .venv
+uv run uvicorn app.main:app --reload     # http://localhost:8000
 ```
 
 **Frontend:**
@@ -39,7 +32,7 @@ docker-compose up
 
 **Backend tests:**
 ```bash
-cd backend && pytest
+cd backend && uv run pytest
 ```
 
 **Frontend tests:**
@@ -48,63 +41,37 @@ cd frontend && npm test          # Vitest unit tests
 cd frontend && npm run test:e2e  # Playwright E2E
 ```
 
-**Lint / format:**
+**Lint / format / typecheck:**
 ```bash
-cd backend && ruff check . && ruff format .
-cd frontend && npm run lint && npm run format
+cd backend && uv run ruff check . && uv run ruff format . && uv run mypy app
+cd frontend && npm run lint && npm run format && npx tsc --noEmit
 ```
 
----
-
-### v2 (R/Shiny — legacy, `main` branch)
-
-**From RStudio:**
-1. Open `Arena3Dweb.Rproj`
-2. Open `server.R`, select "Run External", click "Run App"
+## Architecture Overview
 
-**Via Docker:**
-```bash
-docker pull pavlopouloslab/arena3dweb
-docker run -p 3838:3838 pavlopouloslab/arena3dweb
-```
+### Backend (`backend/app/`)
+Stateless FastAPI — the frontend holds all scene state; the server validates input and runs the graph algorithms.
 
-**From R CLI:**
-```r
-shiny::runApp('.')
-```
+- `main.py` — app + router registration; `config.py` — constants (limits, palettes, scale targets) served at `GET /api/config`.
+- `models/` — Pydantic request/response models (`network`, `layout`, `topology`, `session`, `attributes`).
+- `routers/` — one per endpoint: `config`, `network` (TSV upload), `layout`, `topology`, `session` (import/export), `external` (token-shared sessions), `attributes` (node/edge attribute files).
+- `services/` — logic: `parser` (TSV parse/validate), `graph` (igraph construction + scopes), `layouts` (11 layout algos), `clustering` (4 community algos, optional layout step), `topology` (Degree / Clustering Coefficient / Betweenness), `session`, `attributes`.
+- Algorithms use **python-igraph** — same C core as R's igraph, so layouts/clustering/topology port 1:1.
 
-## Architecture Overview
+### Frontend (`frontend/src/`)
+- `main.ts` — entry point: fetch config → set up Three.js → mount canvas → wire panels + listeners → `animate()`. Exposes `window.__arena = { ctx, history }` as a Playwright test hook (the WebGL canvas is opaque to the a11y tree).
+- `three/` — `Scene`, `Layer`, `Node`, `Edge` classes on npm `three` r170; `runtime.ts` holds the shared mutable `ctx` (replaces v2 ambient globals); `constants.ts` static geometry/palette constants.
+- `actions/` — one module per domain (`network`, `layout`, `layer`, `node`, `edge`, `labels`, `themes`, `screen`, `canvas_controls`, `nav_controls`, `drag_controls`, `right_click_menu`, `session`). These mutate the object model + `ctx`.
+- `commands/` — `Command` interface + `CommandHistory` (undo/redo); `scene.ts` holds the concrete commands. Every scene mutation that should be undoable routes through a command.
+- `ui/` — one module per navbar panel (`home`, `file`, `layouts`, `scene`, `layer`, `node`, `edge`, `data`, `fps`, `help`), each filling its `#panel-*` pane with Bootstrap DOM and wiring controls to `actions`/`commands`.
+- `bus/` — typed `EventBus` singleton (returns unsubscribe fns); `store/` — typed `AppState` store. Together they replace the old Shiny input/output sync.
+- `api/client.ts` — hand-written typed client mirroring the Pydantic models.
 
-This is an **R/Shiny + Three.js** web application for interactive 3D visualization of multilayered networks.
-
-### R/Shiny Layer (backend)
-- `global.R` — loaded once; imports libraries
-- `ui.R` — loads all JS/CSS, defines the navbar tab layout (Home, File, Layer Selection & Layouts, Scene Actions, Layer Actions, Node Actions, Edge Actions, View Data, FPS, Help)
-- `server.R` — wires all `observeEvent` handlers; calls `initializeServerApp()` on startup
-- `views/` — one R file per UI tab (e.g. `file.R`, `layer.R`), each exporting a `generate*Div()` function
-- `functions/` — server-side logic split by domain:
-  - `input.R` — network file upload and validation
-  - `init.R` — app startup: pushes global constants to JS, attaches download handler
-  - `js_handling.R` — helpers to sync JS state back to Shiny inputs
-  - `render.R` — modal/error/warning rendering
-  - `general.R`, `reset.R`, `edges.R`, `vr.R` — domain-specific handlers
-  - `igraph/` — layout, clustering, topology metric calculations using igraph
-- `config/` — R-side variables (`global_variables.R`, `server_variables.R`, `static_variables.R`, `ui_variables.R`)
-
-### JavaScript Layer (frontend, `www/js/`)
-- **Three.js** (`three/three.js`) — core 3D rendering engine; `matrix4.js` and `drag_controls.js` are Three.js add-ons
-- **Classes** (`classes/`) — `Scene`, `Layer`, `Node`, `Edge` — OOP wrappers around Three.js objects
-- **Object actions** (`object_actions/`) — functions for each entity type: `screen.js`, `network.js`, `layout.js`, `layer.js`, `node.js`, `edge.js`, `labels.js`, `themes.js`, `canvas_controls.js`, `right_click_menu.js`
-- **Shiny bridge** — `rshiny_handlers.js` registers all `Shiny.addCustomMessageHandler("handler_*", ...)` callbacks; `rshiny_update.js` sends data from JS back to Shiny
-- **Config** (`config/`) — `global_variables.js` (runtime globals initialized from R via `handler_initializeGlobals`), `static_variables.js` (constants like color palettes, geometry sizes)
-- `general.js` — utility functions; `event_listeners.js` — mouse/keyboard events; `on_page_load.js` — Three.js canvas setup
-
-### R ↔ JS Communication Pattern
-- **R → JS**: `session$sendCustomMessage("handler_*", payload)` in R calls the registered handler in `rshiny_handlers.js`
-- **JS → R**: Shiny input updates (e.g. `Shiny.setInputValue`) trigger `observeEvent` handlers in `server.R`
-- Constants (MAX_LAYERS, MAX_EDGES, MAX_CHANNELS, channel colors) are defined in R config and pushed to JS globals at startup via `handler_initializeGlobals`
+### Communication
+- **Frontend → backend**: `api.*` calls to `/api/*` (network parse, layout, topology, session, attributes).
+- **Within frontend**: components emit/subscribe on the `EventBus` and read/write the `store`; the render loop reacts to `ctx` flags (`renderInterLayerEdgesFlag`, label flags, etc.).
 
 ### Network Data Model
-- Networks are uploaded as TSV with mandatory columns: `SourceNode`, `SourceLayer`, `TargetNode`, `TargetLayer` (optional: `Weight`, `Channel`, edge color columns)
-- Sessions are exported/imported as JSON containing full node/edge/layer state
-- The REST API endpoint accepts a URL parameter to load a network directly from an external application
+- Networks upload as TSV with mandatory columns `SourceNode`, `SourceLayer`, `TargetNode`, `TargetLayer` (optional: `Weight`, `Channel`, edge color columns).
+- Node/edge attribute files add per-node color/size/url/description and per-edge (optionally per-channel) color.
+- Sessions export/import as JSON with full node/edge/layer/scene state. `POST /api/external` returns a token URL so another app can hand off a session.

CLAUDE.md

@@ -1,23 +1,20 @@
-FROM r-base
-#Description of the image
-LABEL description="Arena3Dweb docker image"
-LABEL maintainer="Fotis Baltoumas<baltoumas@fleming.gr>"
-LABEL version="2.0"
-#set the timezone
-ENV TZ Europe/Athens
-#copy the Rprofile.site file and containing the shiny port and CRAN repo url
-COPY Rprofile.site /usr/lib/R/etc/
+# Production image: nginx serves static Vite build, proxies /api to uvicorn.
+FROM node:22-slim AS frontend-build
+WORKDIR /build
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
 
-# install required R packages
-RUN R -e 'install.packages(c("shiny","shinyjs","shinythemes","igraph","RColorBrewer","jsonlite","tidyr"))'
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends nginx && rm -rf /var/lib/apt/lists/*
+COPY backend/pyproject.toml backend/uv.lock ./
+RUN uv sync --frozen --no-group dev
+COPY backend/app ./app
+COPY nginx/nginx.conf /etc/nginx/nginx.conf
+COPY --from=frontend-build /build/dist /usr/share/nginx/html
 
-# copy the Arena3Dweb directory to the VM 
-COPY ./Arena3Dweb/ /root/Arena3DWeb/
-
-RUN R -e 'install.packages(c("DT", "fst"))'
-
-#expose the shiny port
-EXPOSE 3838
-
-#set the default command to run, ie "R"
-CMD ["R", "-e", "shiny::runApp('/root/Arena3DWeb/')"]
+EXPOSE 8080
+# ponytail: sh -c instead of a supervisor; two processes, container dies if nginx dies
+CMD ["sh", "-c", "uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 & exec nginx -g 'daemon off;'"]