Sankofa/docs/DEVELOPMENT.md

# Development Guide

This guide will help you set up your development environment for Sankofa Phoenix.

## Prerequisites

- Node.js 18+ and pnpm (or npm/yarn)
- PostgreSQL 14+ (for API)
- Go 1.21+ (for Crossplane provider)
- Docker (optional, for local services)

## Initial Setup

### 1. Clone the Repository

```bash
git clone https://github.com/sankofa/Sankofa.git
cd Sankofa
```

### 2. Install Dependencies

```bash
# Main application
pnpm install

# Portal
cd portal
npm install
cd ..

# API
cd api
npm install
cd ..

# Crossplane Provider
cd crossplane-provider-proxmox
go mod download
cd ..
```

### 3. Set Up Environment Variables

Create `.env.local` files:

```bash
# Root .env.local
cp .env.example .env.local

# Portal .env.local
cd portal
cp .env.example .env.local
cd ..

# API .env.local
cd api
cp .env.example .env.local
cd ..
```

### 4. Set Up Database

```bash
# Create database
createdb sankofa

# Run migrations
cd api
npm run db:migrate
```

## Running the Application

### Development Mode

```bash
# Main app (port 3000)
pnpm dev

# Portal (port 3001)
cd portal
npm run dev

# API (port 4000)
cd api
npm run dev
```

### Running Tests

```bash
# Main app tests
pnpm test

# Portal tests
cd portal
npm test

# Crossplane provider tests
cd crossplane-provider-proxmox
go test ./...
```

## Project Structure

```
Sankofa/
├── src/              # Main Next.js app
├── portal/           # Portal application
├── api/              # GraphQL API server
├── crossplane-provider-proxmox/  # Crossplane provider
├── gitops/           # GitOps configurations
├── cloudflare/       # Cloudflare configs
└── docs/             # Documentation
```

## Common Tasks

### Adding a New Component

1. Create component in `src/components/`
2. Add tests in `src/components/**/*.test.tsx`
3. Export from appropriate index file
4. Update Storybook (if applicable)

### Adding a New API Endpoint

1. Add GraphQL type definition in `api/src/schema/typeDefs.ts`
2. Add resolver in `api/src/schema/resolvers.ts`
3. Add service logic in `api/src/services/`
4. Add tests

### Database Migrations

```bash
cd api
# Create migration
npm run db:migrate:create migration-name

# Run migrations
npm run db:migrate
```

## Debugging

### Frontend

- Use React DevTools
- Check browser console
- Use Next.js debug mode: `NODE_OPTIONS='--inspect' pnpm dev`

### Backend

- Use VS Code debugger
- Check API logs
- Use GraphQL Playground at `http://localhost:4000/graphql`

## Code Quality

### Linting

```bash
pnpm lint
```

### Type Checking

```bash
pnpm type-check
```

### Formatting

```bash
pnpm format
```

## Troubleshooting

See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues and solutions.