Skip to content

CLAUDE.md

Latest commit

 

History

History
244 lines (179 loc) · 6.26 KB

CLAUDE.md

File metadata and controls

244 lines (179 loc) · 6.26 KB

CLAUDE.md - Fileglancer Development Guide

This file provides guidance for working with the Fileglancer codebase.

Critical Rule: Always Use Pixi

NEVER use system tools directly. Always run commands through pixi:

# WRONG - Never do this
npm install
pytest
npx playwright install

# CORRECT - Always use pixi
pixi run node-install
pixi run test-backend
cd frontend/ui-tests && pixi run npx playwright install

Pixi manages all dependencies (Python, Node.js, npm packages) in isolated environments. Using system tools bypasses this and can cause version conflicts.

Project Overview

Fileglancer is a web application for browsing, sharing, and managing scientific imaging data using OME-NGFF (OME-Zarr). It has:

  • Backend: FastAPI (Python) - located in fileglancer/
  • Frontend: React/TypeScript with Vite - located in frontend/
  • UI Tests: Playwright E2E tests - located in frontend/ui-tests/

Quick Start

# Initial setup (builds frontend, installs Python package)
pixi run dev-install

# Start development server (port 7878, auto-reloads on backend changes)
pixi run dev-launch

# In another terminal, watch frontend for changes
pixi run dev-watch

View the app at http://localhost:7878

Available Pixi Tasks

Development

Command Description
pixi run dev-install Build frontend and install Python package
pixi run dev-launch Start dev server on port 7878 with auto-reload
pixi run dev-watch Watch frontend for changes and rebuild
pixi run node-install Install frontend npm dependencies
pixi run node-build Build frontend
pixi run pip-install Reinstall Python package

Testing

Command Description
pixi run -e test test-backend Run backend tests with pytest and coverage
pixi run test-frontend Run frontend unit tests with Vitest
pixi run test-ui Run Playwright E2E tests
pixi run test-ui -- --ui --debug Run E2E tests in debug UI mode
pixi run test-ui -- tests/specific.spec.ts Run specific E2E test file
pixi run test-ui -- -g "test description" Run E2E tests matching description

Code Quality

Command Description
pixi run node-check TypeScript type checking
pixi run node-eslint-check Check ESLint rules
pixi run node-eslint-write Fix ESLint issues
pixi run node-prettier-check Check Prettier formatting
pixi run node-prettier-write Fix Prettier formatting

Database

Command Description
pixi run migrate Run database migrations
pixi run migrate-create Create new migration

Container Development

Command Description
pixi run container-rebuild Build/rebuild devcontainer
pixi run container-shell Open shell in container
pixi run container-claude Run Claude Code in container

Testing

Backend Tests

pixi run -e test test-backend

Tests are in tests/ directory. Uses pytest with coverage reporting.

Frontend Unit Tests

pixi run test-frontend

Tests are in frontend/src/__tests__/. Uses Vitest with React Testing Library.

UI Integration Tests (Playwright)

First-time setup - install Playwright browsers:

pixi run node-install-ui-tests
cd frontend/ui-tests && pixi run npx playwright install

Run tests:

pixi run test-ui

Tests are in frontend/ui-tests/tests/. The test server runs on port 7879.

Project Structure

fileglancer/
├── fileglancer/           # Backend Python package
│   ├── app.py            # FastAPI application
│   ├── database.py       # SQLAlchemy models and queries
│   ├── filestore.py      # File system operations
│   ├── settings.py       # Configuration via pydantic-settings
│   ├── model.py          # Pydantic models
│   ├── auth.py           # Authentication
│   ├── cli.py            # CLI commands
│   └── alembic/          # Database migrations
├── frontend/              # React/TypeScript frontend
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── contexts/     # React Context providers
│   │   ├── queries/      # TanStack Query hooks
│   │   ├── hooks/        # Custom React hooks
│   │   ├── utils/        # Utility functions
│   │   └── __tests__/    # Unit tests
│   ├── ui-tests/         # Playwright E2E tests
│   └── package.json
├── tests/                 # Backend tests
├── docs/                  # Documentation
├── pyproject.toml         # Python config and pixi tasks
└── pixi.lock             # Pixi lockfile

Configuration

Copy the template and customize:

cp docs/config.yaml.template config.yaml

Key settings:

  • file_share_mounts: Directories to expose (default: ~/)
  • db_url: Database connection string
  • SSL certificates for HTTPS mode

Pixi Environments

  • default: Standard development
  • test: Includes test dependencies (pytest, coverage)
  • release: Includes release tools (twine, hatch)

Use -e flag to specify environment:

pixi run -e test test-backend
pixi run -e release pypi-build

Troubleshooting

Build Issues

Clean all build artifacts and reinstall:

./clean.sh
pixi run dev-install

Frontend Issues

# Clear node_modules and reinstall
rm -rf frontend/node_modules
pixi run node-install

Playwright Issues

Install browser dependencies:

cd frontend/ui-tests && pixi run npx playwright install

Technology Stack

Backend

  • Python 3.12+
  • FastAPI
  • SQLAlchemy (synchronous)
  • Alembic (migrations)
  • Pydantic (validation)
  • Uvicorn (ASGI server)

Frontend

  • React 18
  • TypeScript 5.8
  • Vite (Rolldown)
  • TanStack Query v5
  • TanStack Table v8
  • Material Tailwind v3
  • Tailwind CSS

Testing

  • pytest (backend)
  • Vitest (frontend unit)
  • Playwright (E2E)

Git Hooks

Pre-push hooks run Prettier and ESLint checks via Lefthook. These run automatically when pushing.

Related Documentation