Development Overview

Development Overview

Welcome to the Global Watch Development Guide. This section covers everything you need to know to set up your local development environment, understand our coding conventions, and start contributing to the codebase.

Quick Start

Get up and running with Global Watch development in minutes:

# 1. Clone the repository
git clone https://github.com/your-org/globalwatch.git
cd globalwatch

# 2. Install dependencies
pnpm install

# 3. Start local Supabase
pnpm supabase:web:start

# 4. Start the development server
pnpm dev

After running these commands, you'll have:

• Web App: http://app.localhost.direct:3000
• Marketing Site: http://localhost.direct:3000
• Supabase Studio: http://localhost.direct:54323

Technology Stack

Global Watch is built with modern technologies:

Development Sections

Setup Guide

Complete instructions for setting up your local development environment:

• Installing prerequisites (Node.js, pnpm, Docker)
• Configuring environment variables
• Starting local services (Supabase, development server)
• HTTPS development setup

Read the Setup Guide →

Coding Conventions

Standards and best practices for contributing code:

• TypeScript conventions and type safety
• Component organization patterns
• File naming conventions
• Testing requirements
• Git commit message format

Read the Conventions Guide →

AI Agents Guide

Guidelines for AI agents (Claude, Amazon Q, Cursor) contributing to Global Watch:

• The 7 Absolute Laws (zero tolerance rules)
• RITO Methodology for structured development
• Package conventions (@kit vs @fw)
• Multi-agent collaboration patterns
• Pre-commit checklist

Read the AI Agents Guide →

Common Commands

Here are the most frequently used commands during development:

Development

# Start all apps with Turbopack
pnpm dev

# Start with HTTPS (requires Caddy)
pnpm dev:https

# Start only the web app
pnpm --filter web dev

# Start only the docs site
pnpm docs:dev

Database

# Start local Supabase
pnpm supabase:web:start

# Stop Supabase
pnpm supabase:web:stop

# Reset database (apply migrations)
pnpm supabase:web:reset

# Generate TypeScript types
pnpm supabase:web:typegen

# Create a new migration
pnpm --filter web supabase:db:diff <migration-name>

Quality Assurance

# Type checking
pnpm typecheck

# Lint and auto-fix
pnpm lint:fix

# Format code
pnpm format:fix

Testing

# Run unit tests
pnpm --filter web test:run

# Run E2E tests
pnpm --filter e2e test

Build

# Build all apps
pnpm build

# Build web app only
pnpm --filter web build

# Build docs site
pnpm docs:build

Package Conventions

Global Watch uses two package namespaces:

@fw Packages

When creating new functionality, always use the @fw namespace:

// ✅ CORRECT - Our custom code
import { PasswordInput } from '@fw/ui/password-input';
import { EntitySettings } from '@fw/entity-settings';

// ❌ WRONG - Don't create in @kit
import { MyCustom } from '@kit/ui/my-custom';

Environment Variables

All environment variables are centralized at the monorepo root:

/                           # Monorepo root
├── .env                    # Shared base config (committed)
├── .env.development        # Development defaults (committed)
├── .env.local              # Local overrides (gitignored)
└── apps/                   # NO .env files in apps/

Important: Never create .env files inside apps/ directories.

Learn more about Environment Variables →

Development Workflow

The recommended workflow for feature development:

1. Create a branch from main
2. Read the relevant documentation before coding
3. Write tests first (TDD approach)
4. Implement the feature following conventions
5. Run quality checks (pnpm typecheck && pnpm lint:fix)
6. Test manually in the browser
7. Create documentation for new features
8. Submit a pull request

Getting Help

If you encounter issues during development:

1. Check the Setup Guide for common issues
2. Review the Architecture Documentation for design questions
3. Search existing GitHub issues
4. Ask in the team communication channel

Next Steps

• Setup Guide - Configure your development environment
• Conventions - Learn our coding standards
• AI Agents Guide - Guidelines for AI contributors
• Architecture Overview - Understand the system design