Arkova MVP

Document anchoring system with cryptographic fingerprinting and on-chain verification.

Local Source Of Truth

The canonical local Arkova checkout is:

/Volumes/Extreme/Arkova/arkova-mvpcopy-main

Use that path for day-to-day work on main. Desktop copies, archived folders, backup drives, and PR worktrees are not the source of truth. See docs/ops/local-source-of-truth.md before moving, deleting, or backing up local Arkova files.

Running Arkova MVP Locally

This guide provides step-by-step instructions for setting up and running the Arkova MVP on your local development machine.

Prerequisites

Before starting, ensure you have the following installed:

Install Supabase CLI (if not installed):

npm install -g supabase

Step 1: Clone the Repository

git clone <repository-url>
cd <project-directory>

Step 2: Set Up Environment Files

⚠️ WARNING: Never commit .env files with real credentials.

Frontend Environment

cp .env.example .env

Edit .env and configure:

# Supabase (Vite requires VITE_ prefix for client-side variables)
VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=<your-anon-key-from-supabase-start>

NODE_ENV=development

Worker Service Environment

cp services/worker/.env.example services/worker/.env

Edit services/worker/.env and configure:

WORKER_PORT=3001
NODE_ENV=development
LOG_LEVEL=info

SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key-from-supabase-start>

# For local development, use mocks
USE_MOCKS=true

Step 3: Install Dependencies

Frontend Dependencies

npm install

Worker Dependencies

cd services/worker
npm install
cd ../..

Step 4: Start Supabase

supabase start

This command will:

• Start PostgreSQL on port 54322
• Start the API on port 54321
• Start Studio (admin UI) on port 54323

⚠️ IMPORTANT: Copy the output keys!

The command outputs anon key and service_role key. You need these for your .env files.

Example output:

API URL: http://127.0.0.1:54321
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 5: Reset Database

This runs all migrations and seeds demo data:

supabase db reset

⚠️ WARNING: This command drops all data. Only run on local development databases.

Step 6: Regenerate TypeScript Types

After any database changes, regenerate types:

npm run gen:types

This updates src/types/database.types.ts with the current schema.

Step 7: Run Tests

All Tests

npm test

RLS Integration Tests

npm run test:rls

⚠️ NOTE: RLS tests require Supabase to be running.

Type Checking

npm run typecheck

Linting

npm run lint

UI Copy Lint (Terminology Check)

npm run lint:copy

Step 8: Start the Frontend

npm run dev

The frontend will be available at: http://localhost:5173

Step 9: Start the Worker Service

In a new terminal:

cd services/worker
npm run dev

The worker will be available at: http://localhost:3001

Health check endpoint: http://localhost:3001/health

Sanity Checklist

After setup, verify the following:

• supabase status shows all services running
• http://127.0.0.1:54323 (Studio) is accessible
• npm test passes
• npm run test:rls passes
• npm run lint passes
• npm run lint:copy passes
• Frontend loads at http://localhost:5173
• Worker health check returns {"status":"healthy"}

Demo Users

The seed data includes these test users:

Common Mistakes

Where Governance Rules Live

Required End-of-Task Checks

Before completing any development task:

# 1. Run all tests
npm test

# 2. Run RLS tests
npm run test:rls

# 3. Type check
npm run typecheck

# 4. Lint code
npm run lint

# 5. Check UI terminology
npm run lint:copy

# 6. Regenerate types if schema changed
npm run gen:types

# 7. Verify types are committed
git diff src/types/database.types.ts

⚠️ IMPORTANT: All checks must pass before merging any code.

Stopping Services

# Stop Supabase
supabase stop

# Stop frontend
# Press Ctrl+C in the terminal running npm run dev

# Stop worker
# Press Ctrl+C in the terminal running the worker

Full Reset

To completely reset your local environment:

supabase stop
supabase start
supabase db reset
npm run gen:types