Skip to content

Development‐Setup

Jump to bottom
Mohamed Abdelaziz ‬‏ edited this page Jun 27, 2026 · 1 revision

Development Setup

Complete guide to set up, run, test, and deploy AxiomID locally.

Prerequisites

Tool Version Notes
Node.js 20+ LTS recommended
npm 10+ Comes with Node.js
Git 2.40+ For rebase workflow
Wrangler 3+ For Cloudflare D1/KV

Install

# Clone the repository
git clone https://github.com/Moeabdelaziz007/AxiomID.git
cd AxiomID

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

Environment Variables

Edit .env.local and fill in:

# Pi Network
NEXT_PUBLIC_PI_API_KEY=
PI_SERVER_API_KEY=

# Cloudflare
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
D1_DATABASE_ID=
KV_NAMESPACE_ID=

# Telegram (optional - for notifications)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

# Gemini (for AI workflows)
GEMINI_API_KEY=

Development

# Start dev server (localhost:3000)
npm run dev

# Type check
npm run type-check

# Lint (zero warnings enforced)
npm run lint

# Run tests
npm test

# Run all CI checks locally
npm run type-check && npm run lint && npm test

Database (Cloudflare D1)

# Login to Cloudflare
npx wrangler login

# Run migrations locally
npx wrangler d1 execute axiomid-db --local --file=migrations/001_init.sql

# Run migrations on production
npx wrangler d1 execute axiomid-db --file=migrations/001_init.sql

Branch Workflow

# Create feature branch
git checkout -b feat/your-feature-name

# Make changes, then commit with ۞ suffix
git commit -m "feat(scope): description ۞"

# Rebase on latest main before PR
git fetch origin
git rebase origin/main

# Push (use force-with-lease after rebase)
git push --force-with-lease origin feat/your-feature-name

# Open PR against main

Resolving Merge Conflicts

# After rebase conflict:
git status
# Edit conflicted files, remove all <<<<<<< HEAD markers
grep -r '<<<<<<' src/

# Stage resolved files
git add .
git rebase --continue

# Push
git push --force-with-lease

Deploy

# Build for production
npm run build

# Deploy to Vercel (auto on main push)
git push origin main
# Vercel deploys automatically via GitHub integration

# Manual deploy
npx vercel --prod

Project Structure

AxiomID/
├── src/
│   ├── app/              # Next.js App Router pages + API routes
│   │   ├── api/          # REST API endpoints
│   │   ├── context/      # React context providers
│   │   └── (routes)/     # Page components
│   ├── components/       # Reusable UI components
│   │   ├── dashboard/    # Dashboard-specific components
│   │   ├── passport/     # Passport/identity components
│   │   └── ui/           # Base UI primitives
│   ├── lib/              # Core logic
│   │   ├── auth/         # Authentication (Tier 1 - human only)
│   │   ├── crypto/       # Cryptographic operations (Tier 1)
│   │   ├── pi-sdk/       # Pi Network SDK integration (Tier 1)
│   │   ├── soul/         # Soul System logic
│   │   └── db/           # D1 database queries
│   └── types/            # TypeScript type definitions
├── .github/
│   ├── workflows/        # CI/CD + AI team workflows
│   └── CODEOWNERS        # Ownership tiers
├── migrations/           # D1 SQL migrations
├── public/               # Static assets
└── CONTRIBUTING.md       # Contribution guidelines

Common Issues

npm run lint fails with 0 warnings allowed

# Find lint errors
npm run lint 2>&1 | grep 'error'
# Common fix: replace console.* with logger.*
import { logger } from '@/lib/logger'

Vercel build fails after merge

# Check for stale conflict markers
grep -r '<<<<<<' src/
# Check for type errors
npm run type-check

D1 query timeout in production

# Use batch operations (see PR #139)
await db.batch([stmt1, stmt2, stmt3])

Useful Links

Clone this wiki locally