Development Setup

# Clone the repository
git clone https://github.com/qs-geoflow/geoflow.git
cd geoflow

# Install root dependencies
bun install

# Install all workspace dependencies
bun run clean:all

# Copy environment template
cp .env.example .env

# Edit with your local settings
nano .env

# Database
POSTGRES_PASSWORD=password

# Convex
INSTANCE_SECRET=your-development-secret
INSTANCE_NAME=geoflow-dev

# Development settings
NODE_ENV=development
GEOFLOW_HOST_DATA_PATH=./storage/data
GEOFLOW_HOST_TEMP_PATH=./storage/temp

# Start all services with hot reload
bun run dev

# Or start specific services
bun run dev:geoflow    # Frontend only
bun run dev:backend    # Backend only
bun run dev:motia      # Workflow engine only

# Start with Docker (alternative)
bun run docker:dev

geoflow/
├── apps/
│   ├── geoflow/          # Main React application
│   ├── backend/          # Convex backend
│   ├── motia/            # Workflow engine
│   └── docs/             # Documentation
├── packages/
│   ├── worker/           # PDAL processing service
│   ├── mcp/              # AI analysis service
│   ├── shared/           # Shared utilities
│   └── config/           # TypeScript configs
├── scripts/              # Database scripts
└── storage/              # Data directories

cd apps/geoflow

# Install dependencies
bun install

# Start development server
bun run dev

# Run tests
bun run test

# Format code
bun run format

# Lint code
bun run check

cd apps/backend

# Start development server
bun run dev

# View dashboard
convex dashboard

cd packages/worker

# Install dependencies
bun install

# Start development server
bun run dev

# Test processing
curl -X POST http://localhost:3002/api/process/test

cd apps/motia

# Install dependencies
bun install

# Start development server
bunx motia dev --port 4010

# View dashboard (if available)
open http://localhost:4010

# Lint all packages
bun run lint

# Format all code
bun run format

# Check code (lint + format)
bun run check

# Type checking
bun run type-check

# Run all tests
bun run test

# Run tests for specific package
cd apps/geoflow && bun run test

# Run tests in watch mode
bun run test:watch

# Generate new migration
convex deploy --configure



## API Development

### Convex Queries and Mutations

```typescript
// queries.ts
import { query } from "./_generated/server";

export const getWorkflows = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("workflows").collect();
  },
});

// mutations.ts
import { mutation } from "./_generated/server";

export const createWorkflow = mutation({
  args: { name: v.string(), description: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db.insert("workflows", args);
  },
});

// http.ts
import { httpRouter } from "convex/server";

const http = httpRouter();

http.route({
  path: "/api/webhook",
  method: "POST",
  handler: async (ctx, request) => {
    const body = await request.json();
    // Process webhook
    return new Response("OK");
  },
});

export default http;

// Component test
import { render, screen } from "@testing-library/react";
import { WorkflowCard } from "./WorkflowCard";

test("renders workflow name", () => {
  render(<WorkflowCard workflow={{ name: "Test Workflow" }} />);
  expect(screen.getByText("Test Workflow")).toBeInTheDocument();
});

// API integration test
import { ConvexReactClient } from "convex/react";
import { api } from "../convex/_generated/api";

test("creates workflow", async () => {
  const client = new ConvexReactClient(process.env.CONVEX_URL!);
  const result = await client.mutation(api.workflows.create, {
    name: "Test",
    description: "Test workflow"
  });
  expect(result).toBeDefined();
});

// E2E test with Playwright
import { test, expect } from "@playwright/test";

test("user can create workflow", async ({ page }) => {
  await page.goto("http://localhost:3000");
  await page.click("text=New Workflow");
  await page.fill("[name=name]", "My Workflow");
  await page.click("text=Create");
  await expect(page.locator("text=My Workflow")).toBeVisible();
});

// Add debug logging
console.log("Debug info:", data);

// Use React DevTools
// Install React DevTools browser extension

// Debug Convex queries
import { useQuery } from "convex/react";
const data = useQuery(api.workflows.get, { id });
console.log("Query result:", data);

// Add logging to Convex functions
import { log } from "convex/server";

export const myMutation = mutation({
  args: { data: v.any() },
  handler: async (ctx, args) => {
    log("Processing mutation with data:", args.data);
    // ... function logic
  },
});

# View container logs
docker compose logs -f geoflow-app

# Access container shell
docker compose exec geoflow-app sh

# Debug network issues
docker compose exec geoflow-app curl http://geoflow-convex-backend:3210

# Monitor resource usage
docker stats

// React DevTools Profiler
// Use Chrome DevTools Performance tab

// Monitor bundle size
bun run build
ls -lh dist/static/js/

// Convex dashboard metrics
// View at http://localhost:6791

// Database query performance
EXPLAIN ANALYZE SELECT * FROM workflows;

# Monitor system resources
top
htop

# Docker resource usage
docker stats

# Network monitoring
iftop

# Create feature branch
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "Add new feature"

# Push and create PR
git push origin feature/new-feature

# Stop all services
docker compose down

# Clean up
bun run clean:all

# Remove volumes (WARNING: deletes data)
docker compose down -v

# Reinitialize
bun install
bun run dev