A unified monorepo for all ZKGenomics applications and packages, enabling privacy-preserving genomic data analysis using zero-knowledge proofs.

This monorepo consolidates all ZKGenomics repositories into a single workspace with clear separation of concerns:

zkg-monorepo/
├── apps/                    # Applications
│   ├── api/                 # Backend API (Go) - REST API with PostgreSQL
│   ├── cli/                 # CLI tool (Go) - Command-line interface
│   ├── docs/                # Documentation site (Docusaurus 3.8)
│   ├── marketing-site/      # Marketing website (Astro 5.x + React 19)
│   └── web-app/             # Web application (React 19 + Vite 6.x)
├── libs/                    # Shared Go libraries
│   ├── auth/                # Authentication & authorization utilities
│   ├── config/              # Configuration management
│   └── database/            # Database utilities, migrations & seeders
├── packages/                # Reusable packages
│   ├── proofs/              # Core ZK proofs library (Go + Consensys Gnark)
│   └── shared-types/        # TypeScript type definitions (@zkgenomics/shared-types)
└── tools/                   # Build & deployment tools
    ├── docker/              # Docker configurations (distributed per app)
    └── scripts/             # Build & deployment scripts

This monorepo uses Nix flakes to provide a reproducible development environment with all required dependencies pre-installed.

# Clone the repository
git clone <repository-url>
cd zkg-monorepo

# Enter Nix development shell (installs all dependencies automatically)
nix develop

# Install JavaScript/TypeScript dependencies  
pnpm install && go work sync

# Start all applications
pnpm dev

What's included in the Nix environment:

• Go 1.24.5 - Backend development
• Node.js 20.19.4 - Frontend development
• pnpm 10.12.4 - Package management
• golangci-lint - Go linting
• Git, curl, jq - Development utilities
• Docker & docker-compose - Containerization

For automatic shell activation when entering the directory:

# Install direnv (if not already installed)
# The .envrc file will automatically activate the Nix environment

If you prefer not to use Nix, install dependencies manually:

• Node.js: ≥20.0.0
• pnpm: ≥9.0.0 (currently using 10.12.4)
• Go: 1.24.4+
• golangci-lint: Latest stable version
• Docker: Latest stable version
• PostgreSQL: For API database (if running locally)

1. Clone the repository:

git clone <repository-url>
cd zkg-monorepo

2. Install JavaScript dependencies:

pnpm install

3. Initialize Go workspace:

go work sync

All scripts use Turborepo 2.5.5 for optimal caching and parallelization. Run these commands within the Nix environment (nix develop) for best results:

# Development (in Nix environment)
nix develop       # Enter reproducible development environment
pnpm dev          # Start all applications in development mode
pnpm build        # Build all applications and packages
pnpm test         # Run tests across all packages
pnpm lint         # Lint all code (ESLint 9.x + golangci-lint)
pnpm format       # Format all code (prettier + gofmt)
pnpm format:check # Check code formatting (used in CI)
pnpm type-check   # TypeScript type checking
pnpm clean        # Clean all build artifacts

Benefits of Nix environment:

• ✅ Reproducible builds - Same environment locally and in CI
• ✅ No version conflicts - Exact dependency versions guaranteed
• ✅ Fast setup - Dependencies cached and shared across team
• ✅ CI/Local parity - GitHub Actions uses identical environment

Note: Turborepo intelligently handles mixed Go/JavaScript builds with proper dependency resolution and caching.

cd apps/web-app
pnpm dev          # Start development server (typically :5173)
pnpm build        # Build for production (outputs to dist/)
pnpm preview      # Preview production build
pnpm lint         # ESLint with React hooks plugin

cd apps/api
go run main.go    # Start development server
go build          # Build binary
go test ./...     # Run tests

cd apps/cli
go run cmd/main.go --help    # Show CLI help
go build -o zkgenomics cmd/main.go  # Build CLI binary

cd apps/docs
pnpm start        # Start development server (typically :3000)
pnpm build        # Build static site (outputs to build/)
pnpm serve        # Serve built site locally
pnpm type-check   # TypeScript checking

cd apps/marketing-site
pnpm dev          # Start development server (typically :4321)
pnpm build        # Build static site (outputs to dist/)
pnpm preview      # Preview production build
pnpm type-check   # TypeScript checking

This monorepo uses Go 1.24.4 workspaces for managing 6 Go modules:

• apps/api - REST API server
• apps/cli - Command-line tool
• libs/auth - Authentication utilities
• libs/config - Configuration management
• libs/database - Database utilities & migrations
• packages/proofs - Core ZK proofs library

# Sync workspace dependencies
go work sync

# Add new module to workspace
go work use ./path/to/new/module

# Build all Go modules
go build ./...

# Test all Go modules
go test ./...

# Run specific module
cd apps/api && go run main.go
cd apps/cli && go run cmd/main.go

• Package Manager: pnpm 10.12.4 with workspaces
• Build System: Turborepo 2.5.5
• Workspace Config: pnpm-workspace.yaml includes apps/*, packages/*, libs/*, tools/*
• Dependencies: Centralized lockfile (pnpm-lock.yaml) with workspace protocol
• Shared Types: @zkgenomics/shared-types consumed via workspace:*

• Module Management: Go 1.24.4 workspaces (go.work)
• Dependencies: Individual go.mod files with shared workspace resolution
• Cross-module: Automatic dependency resolution between internal modules
• Shared Libraries: libs/* available to all applications via workspace

Run tests across the entire monorepo:

# All tests (Turborepo handles mixed JS/Go intelligently)
pnpm test

# Go tests only (all workspace modules)
go test ./...

# JavaScript/TypeScript tests only
pnpm test --filter="apps/web-app" --filter="apps/docs" --filter="apps/marketing-site" --filter="packages/shared-types"

# Test specific application
pnpm test --filter="web-app"  # React app tests
cd apps/api && go test ./...   # API tests
cd packages/proofs && go test ./...  # ZK proofs tests

Build all applications for production:

# Build everything
pnpm build

# Build specific app
pnpm build --filter=web-app
pnpm build --filter=docs

For Go applications:

# Build API server
cd apps/api && go build -o api main.go

# Build CLI tool  
cd apps/cli && go build -o zkgenomics cmd/main.go

# Build ZK proofs library (if needed)
cd packages/proofs && go build ./...

# Build all Go modules
go build ./...  # From monorepo root

Each application has its own Dockerfile:

• apps/api/Dockerfile - Go API server
• apps/web-app/Dockerfile - React application
• apps/docs/Dockerfile - Docusaurus documentation
• apps/marketing-site/Dockerfile - Astro marketing site

# API server with database
cd apps/api && docker compose up -d

# Build individual application
cd apps/web-app && docker build -t zkgenomics-web .
cd apps/api && docker build -t zkgenomics-api .

Note: Centralized Docker configurations in tools/docker/ are planned but not yet implemented.

All CI/CD workflows use the same Nix environment as local development:

# .github/workflows/pr-checks.yml
- name: Install Nix
  uses: cachix/install-nix-action@v31
- name: Setup Cachix
  uses: cachix/cachix-action@v14
  with:
    name: zkgenomics
    authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'

Benefits:

• ✅ Reproducible CI - Exact same environment as local development
• ✅ Fast builds - Binary caching with Cachix (zkgenomics.cachix.org)
• ✅ Simplified workflows - Single Nix setup replaces multiple tool installations
• ✅ No tool version drift - CI always uses exact versions from flake.nix

All deployment workflows (API, web app, docs, marketing site) use Nix for consistent builds across environments.

• Copy .env.example to .env in each application directory (where available)
• Configure database connections, API keys, and other secrets
• Never commit .env files to version control

• API: apps/api/config.yaml - Server configuration, database settings
• CLI: apps/cli/config.example.json - CLI tool configuration template
• Web App: Environment variables and vite.config.ts - Vite build configuration
• Docs: docusaurus.config.ts - Documentation site configuration
• Marketing: astro.config.mjs - Astro build configuration

• api: Go-based REST API server with PostgreSQL
• cli: Command-line interface for ZKGenomics operations
• docs: Technical documentation built with Docusaurus
• marketing-site: Public website built with Astro
• web-app: React-based user interface

Shared Go libraries used across applications:

• auth: Authentication and authorization utilities
• config: Configuration management
• database: Database connections, migrations, and utilities

• proofs: Core zero-knowledge proof generation and verification (Go + Consensys Gnark)
  • Supports BRCA1, eye color, chromosome analysis, and dynamic proofs
  • VCF file processing capabilities
• shared-types: TypeScript type definitions shared across applications
  • Comprehensive types for auth, genomic data, API responses, React components
  • Currently consumed by web-app, available for all TypeScript projects

1. Setup environment: nix develop (or use direnv for automatic activation)
2. Create a feature branch from main
3. Install dependencies: pnpm install && go work sync
4. Make your changes
5. Run quality checks:

   pnpm lint          # Lint all code
   pnpm format:check  # Check code formatting
   pnpm type-check    # TypeScript type checking
   pnpm test          # Run all tests
   pnpm build         # Build to ensure no breakages

6. Submit a pull request

Benefits of Nix workflow:

• ✅ Same environment as CI - no "works on my machine" issues
• ✅ All required tools automatically available
• ✅ Reproducible builds and consistent formatting

All code formatting and linting is enforced via CI:

• JavaScript/TypeScript: ESLint 9.x + TypeScript-ESLint 8.x + Prettier 3.3.3
• Go: golangci-lint + gofmt (automatic formatting)
• Astro: Prettier with astro plugin
• Markdown/MDX: Prettier formatting
• Commit messages: Conventional Commits format recommended

Important: CI will fail if code is not properly formatted. Run pnpm format to fix formatting issues.

• Architecture Documentation - Detailed monorepo architecture and implementation status
• API Documentation - Technical documentation (Docusaurus)
• ZK Proofs Library - Core zero-knowledge proofs implementation
• Shared Types - TypeScript type definitions
• Project Tasks - Current development tasks and roadmap

MIT License - see LICENSE for details.

• Issues: GitHub Issues
• Documentation: docs/
• Discussions: GitHub Discussions