Galipo Legal Case Management Development

Development guidance for working with the Galipo codebase - a legal case management system for personal injury law firms.

What This Skill Does

Provides comprehensive context for developing Galipo, which operates as:

**MCP server** with 41+ tools for Claude AI integration (FastMCP)

**React web dashboard** for managing cases, tasks, deadlines, and contacts

Architecture Overview

```

main.py # FastAPI + MCP server entry point

├── db/ # Database layer (connection, domain queries)

├── tools/ # MCP tools (AI interface)

├── routes/ # REST API endpoints (web UI interface)

└── frontend/src/

├── pages/ # Route pages

├── components/ # UI components by domain

├── api/ # API client functions

└── types/ # TypeScript interfaces

```

Development Commands

Backend (Python/FastAPI)

```bash

Development server with hot reload

uvicorn main:app --reload --port 8000

Production server

python main.py

Run database migrations

python migrations/run_migration.py

Run specific migration

python migrations/run_migration.py <migration_file.sql>

```

Frontend (React/Vite)

```bash

cd frontend

npm run dev # Dev server at http://localhost:5173

npm run build # Production build

npm run lint # ESLint

npm run type-check # TypeScript type checking

```

Database Operations

```bash

Connect to database

psql $DATABASE_URL

Backup/restore

./scripts/backup.sh

./scripts/restore.sh <backup_file>

Reset database (development only)

RESET_DB=true python main.py

Generate schema diagram

python scripts/generate_schema_diagram.py

```

**Note**: Schema diagram at `docs/schema.md` auto-updates via pre-commit hook when migrations or `db/connection.py` change.

Local Development Workflow

Starting Services

**Always use `/dev` to start/restart all development servers**. This ensures:

PostgreSQL is running

Backend (FastAPI on port 8000) starts/restarts

Frontend (Vite on port 5173) starts/restarts

All services are healthy

Use `/dev`:

At start of coding sessions

After pulling new changes

When services seem unresponsive

After changing environment variables or dependencies

Logs are at: `/tmp/backend_$BACKEND_PORT.log` and `/tmp/frontend_$VITE_PORT.log`

Multi-Repo Development

For working on multiple branches simultaneously with isolated databases:

**Port allocation:**

|------|---------|----------|----------|

| mcp-galipo | 8000 | 5173 | galipo |

| mcp-galipo_2 | 8001 | 5174 | galipo_2 |

| mcp-galipo_3 | 8002 | 5175 | galipo_3 |

**Setup steps:**

1. Create databases:

```bash

/Applications/Postgres.app/Contents/Versions/latest/bin/psql postgres -c "CREATE DATABASE galipo_2;"

/Applications/Postgres.app/Contents/Versions/latest/bin/psql postgres -c "CREATE DATABASE galipo_3;"

```

2. Copy repo:

```bash

cd ~/Code

cp -r mcp-galipo mcp-galipo_2

cp -r mcp-galipo mcp-galipo_3

```

3. Update `.env` in each copy (change only these values):

```bash

mcp-galipo_2

DATABASE_URL=postgresql://YOUR_USER@localhost:5432/galipo_2

PORT=8001

BACKEND_PORT=8001

VITE_PORT=5174

mcp-galipo_3

DATABASE_URL=postgresql://YOUR_USER@localhost:5432/galipo_3

PORT=8002

BACKEND_PORT=8002

VITE_PORT=5175

```

4. Reinstall frontend dependencies:

```bash

cd mcp-galipo_2/frontend && rm -rf node_modules && npm install

cd mcp-galipo_3/frontend && rm -rf node_modules && npm install

```

5. Start each with `/dev` in separate Claude Code sessions

6. Optionally seed test data:

```bash

cd mcp-galipo_2

set -a && source .env && set +a

.venv/bin/python seed_dev_data.py

```

Key Patterns and Conventions

Backend Patterns

**Modular structure**: Each domain (cases, tasks, events, persons) has separate files in `db/`, `tools/`, and `routes/`

**Context manager for DB**: Always use `with get_cursor() as cur:` for database operations (auto-commits/rollbacks)

**Validation functions**: `db/validation.py` has validators like `validate_case_status()`, `validate_date_format()`

**MCP tools** return dicts/lists; **routes** return FastAPI responses

Frontend Patterns

**TanStack Query** for server state (mutations invalidate related queries)

**TanStack Table** for data tables with sorting/filtering

**@dnd-kit** for drag-and-drop task reordering

**Tailwind CSS** for styling (utility classes)

API calls go through `frontend/src/api/` functions

Database Design

**JSONB columns** for flexible data (e.g., `persons.attributes` stores type-specific fields)

**case_persons** junction table links persons to cases with role and side

**tasks.order_index** for drag-and-drop ordering; `db/tasks.py` has `reorder_task()` logic

Critical Dockerfile Requirement

**When adding new Python directories/modules**, update the `Dockerfile` to include them:

```dockerfile

COPY main.py database.py tools.py routes.py auth.py ./

COPY db/ ./db/

COPY tools/ ./tools/

COPY routes/ ./routes/

COPY services/ ./services/

Add new packages here

```

Missing COPY lines cause production `ModuleNotFoundError`. Ensure new packages have `__init__.py`.

Pre-Commit Verification

**Run `/verify` before pushing changes that affect:**

Database schema

Migrations

`db/*.py` functions

The `/verify` skill checks:

Migration safety (idempotent, preserves data, correct FK order)

Type consistency across all layers

API contract consistency

Build verification

Export completeness

**Critical**: Live production database receives schema changes automatically on app restart. No manual migration step exists - `migrate_db()` runs on startup.

Environment Variables

|----------|----------|---------|-------------|

| `PORT` | No | 8000 | Backend server port (uvicorn) |

| `BACKEND_PORT` | No | 8000 | Backend port (Vite proxy config) |

| `VITE_PORT` | No | 5173 | Frontend dev server port |

Service Endpoints

**Frontend**: http://localhost:5173 (Vite dev server)

**Backend API**: http://localhost:8000/api/v1/*

**MCP Server**: http://localhost:8000/sse

**Legacy frontend**: http://localhost:8000/legacy

Git Workflow

**Never push automatically.** The user handles `git push` manually. Only commit when asked.

Development uses [lazygit](https://github.com/jesseduffield/lazygit) in a separate terminal to monitor git activity and handle pushes.

Available MCP Tools

Project MCP servers in `.mcp.json`:

**postgres** - Database queries (read-only mode)

**context7** - Library documentation lookup

**sequential-thinking** - Structured step-by-step reasoning

**Note**: Only use `sequential-thinking` MCP when explicitly requested by the user.

Database Schema Reference

The database uses a person-centric model where:

`persons` table stores all entities (clients, attorneys, judges, experts, etc.)

`case_persons` junction table links persons to cases with role and side

JSONB `attributes` columns store role-specific data

Schema diagram auto-generates at `docs/schema.md`

Implementation Guidelines

1. **Use `/dev` liberally** to ensure services are running correctly

2. **Run `/verify` before pushing** database or type-related changes

3. **Update Dockerfile** when adding new Python packages

4. **Follow modular structure** - keep domain logic separated in `db/`, `tools/`, `routes/`

5. **Use context managers** for all database operations

6. **Invalidate queries** after mutations in frontend

7. **Never auto-push** - user handles git push manually

Future Considerations

The codebase includes notes about planned person schema simplifications where role would drive UI instead of separate type fields, with person-level attributes for inherent/stable data and case-level attributes for engagement-specific overrides.

Galipo Legal Case Management Development

Galipo Legal Case Management Development

What This Skill Does

Architecture Overview

Development Commands

Backend (Python/FastAPI)

Development server with hot reload

Production server

Run database migrations

Run specific migration

Frontend (React/Vite)

Database Operations

Connect to database

Backup/restore

Reset database (development only)

Generate schema diagram

Local Development Workflow

Starting Services

Multi-Repo Development

mcp-galipo_2

mcp-galipo_3

Key Patterns and Conventions

Backend Patterns

Frontend Patterns

Database Design

Critical Dockerfile Requirement

Add new packages here

Pre-Commit Verification

Environment Variables

Service Endpoints

Git Workflow

Available MCP Tools

Database Schema Reference

Implementation Guidelines

Future Considerations

Reviews (0)