Sparki Developer Getting Started Guide

Last Updated: December 2025
For: Developers, DevOps Engineers, Site Reliability Engineers
Target Audience: New team members, external contributors, development teams

Quick Start

What You’ll Need (5 minutes)

# 1. Clone the repository
git clone https://github.com/sparki/sparki-tools.git
cd sparki.tools

# 2. Run setup script
./scripts/dev-setup.sh

# 3. Verify installation
docker --version
kubectl version --client
terraform --version
aws --version

Your First Deployment (5 minutes)

# Navigate to infrastructure
cd infrastructure/terraform

# Preview changes
terraform plan -target=kubernetes_namespace.default

# Deploy
terraform apply -auto-approve -target=kubernetes_namespace.default

# Verify
kubectl get namespaces | grep sparki

View Local Dashboards (2 minutes)

# Port forward to Grafana
kubectl port-forward -n monitoring svc/grafana 3000:80

# Open browser to http://localhost:3000
# Username: admin
# Password: (check .env file)

Development Environment Setup

System Requirements

Minimum:

macOS 11+ / Ubuntu 20.04+ / Windows 10+ (with WSL2)
8GB RAM (16GB recommended)
50GB free disk space
Broadband internet (for Docker image pulls)

For Local Kubernetes:

Docker Desktop 4.0+ (macOS/Windows)
Or: Colima (lightweight alternative for macOS)
Or: Minikube (cross-platform)

Installation Steps

1. Install Core Tools (macOS)

# Using Homebrew (fastest)
brew install terraform kubectl helm aws-cli docker

# Or: Install Docker Desktop (includes Docker + Kubernetes)
brew install --cask docker

2. Install Core Tools (Ubuntu)

# Update package manager
sudo apt update && sudo apt upgrade -y

# Install tools
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
sudo apt install terraform kubectl helm awscli

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

3. Configure AWS Credentials

# Configure AWS CLI
aws configure

# When prompted:
# AWS Access Key ID: [your-key]
# AWS Secret Access Key: [your-secret]
# Default region: us-east-1
# Default output format: json

# Verify
aws sts get-caller-identity

4. Setup Local Kubernetes (Docker Desktop)

# Enable Kubernetes in Docker Desktop
# macOS: Docker Desktop → Preferences → Kubernetes → Enable Kubernetes
# Windows: Docker Desktop → Settings → Kubernetes → Enable Kubernetes

# Wait 2-3 minutes for Kubernetes to start
kubectl cluster-info

# Should show:
# Kubernetes master is running at https://kubernetes.docker.internal:6443

5. Setup kubeconfig for EKS (if connecting to existing cluster)

# Get cluster name
export CLUSTER_NAME=sparki-eks
export AWS_REGION=us-east-1

# Update kubeconfig
aws eks update-kubeconfig \
  --region $AWS_REGION \
  --name $CLUSTER_NAME

# Verify connection
kubectl cluster-info
kubectl get nodes

Verification Checklist

# Run this script to verify setup
cat > ~/verify-setup.sh << 'EOF'
#!/bin/bash

echo "=== Sparki Developer Environment Verification ==="

# Check Docker
echo "✓ Docker:"
docker --version

# Check Kubernetes
echo "✓ Kubernetes:"
kubectl version --client

# Check Terraform
echo "✓ Terraform:"
terraform version

# Check Helm
echo "✓ Helm:"
helm version

# Check AWS CLI
echo "✓ AWS CLI:"
aws --version

# Check Git
echo "✓ Git:"
git --version

# Check kubeconfig
echo "✓ Kubeconfig:"
kubectl config current-context

echo ""
echo "All tools ready! ✅"
EOF

chmod +x ~/verify-setup.sh
~/verify-setup.sh

Project Architecture Overview

High-Level Architecture

┌─────────────────────────────────────────────────────┐
│              Developer Laptop (Local)               │
├─────────────────────────────────────────────────────┤
│  Docker Desktop with Local Kubernetes (Minikube)    │
│  ├── PostgreSQL (local)                             │
│  ├── Redis (local)                                  │
│  └── Backend Services (docker-compose)              │
├─────────────────────────────────────────────────────┤
│  IDE (VS Code, GoLand)                              │
│  ├── Backend code (Go)                              │
│  ├── Web frontend (Next.js/React)                   │
│  ├── Mobile app (Flutter)                           │
│  └── Infrastructure code (Terraform/Helm)           │
├─────────────────────────────────────────────────────┤
│  Git Repository (GitHub)                            │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│     CI/CD Pipeline (GitHub Actions)                 │
├─────────────────────────────────────────────────────┤
│  Stage 1: Lint & Test (Go tests, JavaScript tests)  │
│  Stage 2: Build (Docker images, artifacts)          │
│  Stage 3: Push (Container registry)                 │
│  Stage 4: Deploy (Terraform apply)                  │
│  Stage 5: Verify (Integration tests)                │
│  Stage 6: Monitor (Health checks, logs)             │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│       AWS EKS Cluster (Production)                  │
├─────────────────────────────────────────────────────┤
│  Control Plane (AWS managed)                        │
│  Worker Nodes (EC2 instances)                       │
│  Load Balancer (AWS ALB)                            │
│  Storage (RDS PostgreSQL, ElastiCache Redis)        │
│  Logging (CloudWatch, Loki)                         │
│  Monitoring (Prometheus, Grafana)                   │
│  Security (WAF, RBAC, Pod Security Standards)       │
│  Encryption (KMS, TLS/mTLS)                         │
└─────────────────────────────────────────────────────┘

Technology Stack

Backend:

Language: Go 1.20+
Framework: Echo or similar HTTP framework
Database: PostgreSQL 13+
Cache: Redis 6+
Container: Docker
Orchestration: Kubernetes (EKS)

Frontend:

Framework: Next.js 14+
Language: TypeScript
Styling: Tailwind CSS
Testing: Vitest + Playwright

Mobile:

Framework: Flutter
Language: Dart
State Management: Provider/Riverpod

Infrastructure:

IaC: Terraform 1.0+
Configuration: Helm Charts
Secrets: Kubernetes Secrets (encrypted with KMS)
Security: Network Policies, RBAC, Pod Security Standards

Directory Structure

sparki.tools/
├── backend/                    # Go backend services
│   ├── main.go
│   ├── api/                   # API handlers
│   ├── internal/              # Business logic
│   ├── pkg/                   # Shared packages
│   ├── go.mod
│   ├── go.sum
│   └── Dockerfile
├── web/                        # Next.js frontend
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   └── styles/
│   ├── package.json
│   ├── tsconfig.json
│   └── Dockerfile
├── mobile/                     # Flutter mobile app
│   ├── lib/
│   ├── pubspec.yaml
│   └── Dockerfile
├── infrastructure/             # Terraform & Kubernetes
│   ├── terraform/
│   │   ├── main.tf
│   │   ├── modules/           # Reusable modules
│   │   └── environments/       # dev, staging, prod
│   └── helm/                  # Helm charts
├── docs/                       # Documentation
│   ├── architecture/
│   ├── api/
│   ├── guides/
│   └── runbooks/
├── scripts/                    # Utility scripts
│   ├── dev-setup.sh
│   ├── deploy.sh
│   ├── health-check.sh
│   └── logs.sh
├── docker-compose.dev.yml     # Local development
├── docker-compose.test.yml    # Testing
└── Makefile                   # Common commands

Local Development Workflow

Start Your Development Environment

Option 1: Docker Compose (Simplest)

# Start all services locally
docker-compose -f docker-compose.dev.yml up -d

# Services running:
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Backend: localhost:3000
# - Frontend: localhost:3001

# Verify services
docker-compose -f docker-compose.dev.yml ps

# View logs
docker-compose -f docker-compose.dev.yml logs -f backend

# Stop everything
docker-compose -f docker-compose.dev.yml down

Option 2: Local Kubernetes

# Start local Kubernetes cluster
kubectl cluster-info

# Create namespace
kubectl create namespace sparki-dev

# Deploy database
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install postgres bitnami/postgresql \
  -n sparki-dev \
  --set auth.password=devpassword

# Deploy backend
docker build -t sparki-backend:dev backend/
docker load -i sparki-backend:dev.tar  # Load into local Docker

kubectl apply -f infrastructure/helm/backend/values-dev.yaml

# Verify
kubectl get pods -n sparki-dev
kubectl logs -n sparki-dev -l app=backend -f

Develop Backend Service

# Navigate to backend
cd backend

# Install dependencies
go mod download
go mod tidy

# Run tests
go test ./...

# Run with live reload
go install github.com/cosmtrek/air@latest
air  # Watches files and auto-rebuilds

# Build Docker image
docker build -t sparki-backend:dev .

# Run locally
docker run -p 3000:3000 sparki-backend:dev

Develop Frontend

# Navigate to frontend
cd web

# Install dependencies
npm install

# Start dev server (with hot reload)
npm run dev

# Open browser to http://localhost:3001

# Run tests
npm test

# Build for production
npm run build

# Lint and format
npm run lint
npm run format

Database Development

# Connect to local PostgreSQL
psql -h localhost -U postgres -d sparki_dev

# Run migrations
go run ./cmd/migrate/main.go

# Create test data
go run ./cmd/seed/main.go

# Monitor database
docker exec -it docker_postgres_1 psql -U postgres -d sparki_dev

Make Common Commands

# View available commands
make help

# Common tasks
make dev              # Start development environment
make test            # Run all tests
make build           # Build all containers
make deploy-dev      # Deploy to dev environment
make logs-backend    # Stream backend logs
make db-migrate      # Run database migrations
make clean           # Clean up containers and volumes

First Deployment

Deploy to Development Environment (15 minutes)

Step 1: Prepare Code

# Ensure code is clean
git status
git pull origin main

# Create feature branch
git checkout -b feature/my-feature

Step 2: Build Images

# Build all containers
docker-compose -f docker-compose.dev.yml build

# Tag images
docker tag sparki-backend:latest \
  ghcr.io/sparki/backend:${GIT_SHA}
docker tag sparki-web:latest \
  ghcr.io/sparki/web:${GIT_SHA}

# Push to registry (if using private registry)
docker push ghcr.io/sparki/backend:${GIT_SHA}
docker push ghcr.io/sparki/web:${GIT_SHA}

Step 3: Deploy via Terraform

# Navigate to infrastructure
cd infrastructure/terraform

# Plan changes
terraform plan \
  -var="backend_image=ghcr.io/sparki/backend:${GIT_SHA}" \
  -var="environment=dev"

# Apply changes
terraform apply \
  -auto-approve \
  -var="backend_image=ghcr.io/sparki/backend:${GIT_SHA}" \
  -var="environment=dev"

Step 4: Verify Deployment

# Check pods running
kubectl get pods -n sparki-dev

# Wait for deployment to be ready
kubectl rollout status deployment/backend -n sparki-dev

# Port forward to test
kubectl port-forward -n sparki-dev svc/backend 3000:3000

# In another terminal
curl http://localhost:3000/health

# View logs
kubectl logs -n sparki-dev -l app=backend -f

Deploy to Staging/Production

# Create pull request for code review
git push origin feature/my-feature
# Go to GitHub and create PR

# Once approved and merged
git checkout main
git pull origin main

# Tag release
git tag v1.2.3
git push origin v1.2.3

# Deployment happens automatically via CI/CD
# Monitor in GitHub Actions

Common Development Tasks

Task: Add New API Endpoint

// backend/api/handlers.go

// 1. Add handler function
func GetUserProfile(c echo.Context) error {
    userID := c.Param("id")

    user, err := getUserFromDB(userID)
    if err != nil {
        return c.JSON(http.StatusInternalServerError, err)
    }

    return c.JSON(http.StatusOK, user)
}

// 2. Register route (main.go or router.go)
e.GET("/api/v1/users/:id", GetUserProfile)

// 3. Test endpoint
curl http://localhost:3000/api/v1/users/123

// 4. Add integration test
func TestGetUserProfile(t *testing.T) {
    // Test implementation
}

Task: Modify Database Schema

# 1. Create migration
touch backend/migrations/$(date +%s)_add_user_email.sql

# 2. Write migration
cat > backend/migrations/1701234567_add_user_email.sql << 'EOF'
-- Upgrade
ALTER TABLE users ADD COLUMN email VARCHAR(255);

-- Downgrade
ALTER TABLE users DROP COLUMN email;
EOF

# 3. Run migration
go run ./cmd/migrate/main.go

# 4. Test in code
// Query updated schema

Task: Add Frontend Component

// web/src/components/UserCard.tsx

import { FC } from "react";
import { User } from "@/types/user";

interface UserCardProps {
    user: User;
    onEdit?: (user: User) => void;
}

export const UserCard: FC<UserCardProps> = ({ user, onEdit }) => {
    return (
        <div className="p-4 border rounded-lg">
            <h3 className="font-bold">{user.name}</h3>
            <p className="text-gray-600">{user.email}</p>
            {onEdit && <button onClick={() => onEdit(user)}>Edit</button>}
        </div>
    );
};

// 1. Add tests
import { render, screen } from "@testing-library/react";

describe("UserCard", () => {
    it("renders user information", () => {
        const user = { id: 1, name: "John", email: "john@example.com" };
        render(<UserCard user={user} />);
        expect(screen.getByText("John")).toBeInTheDocument();
    });
});

// 2. Use in page
import { UserCard } from "@/components/UserCard";

export default function UsersPage() {
    return (
        <div>
            {users.map((user) => (
                <UserCard key={user.id} user={user} />
            ))}
        </div>
    );
}

Task: Configure New Infrastructure

# infrastructure/terraform/modules/my-service/main.tf

resource "kubernetes_deployment" "my_service" {
  metadata {
    name      = "my-service"
    namespace = var.namespace
  }

  spec {
    replicas = var.replicas

    selector {
      match_labels = {
        app = "my-service"
      }
    }

    template {
      metadata {
        labels = {
          app = "my-service"
        }
      }

      spec {
        container {
          name  = "my-service"
          image = var.image

          port {
            container_port = 3000
          }

          env {
            name  = "DATABASE_URL"
            value = var.database_url
          }
        }
      }
    }
  }
}

# Use module
module "my_service" {
  source = "./modules/my-service"

  namespace = "sparki-dev"
  replicas  = 2
  image     = "ghcr.io/sparki/my-service:latest"
}

Debugging & Troubleshooting

View Logs

# Backend logs (local)
docker logs -f docker_backend_1

# Backend logs (Kubernetes)
kubectl logs -n sparki-dev deployment/backend
kubectl logs -n sparki-dev -f -l app=backend --all-containers=true

# Stream all service logs
kubectl logs -n sparki-dev -f --all-containers=true --prefix=true

Debug Database Connection

# Check PostgreSQL is running
docker ps | grep postgres

# Connect to database
psql -h localhost -U postgres -d sparki_dev

# Run query
SELECT * FROM users;

# Check connection from backend
curl http://localhost:3000/health/db

Debug Kubernetes Deployment

# Get deployment status
kubectl describe deployment backend -n sparki-dev

# Check recent events
kubectl get events -n sparki-dev --sort-by='.lastTimestamp'

# Exec into pod for debugging
kubectl exec -it deployment/backend -n sparki-dev -- /bin/sh

# Inside pod:
# - Check environment variables
env | grep DATABASE

# - Check network connectivity
curl http://postgres:5432

# - Check logs
cat /var/log/app.log

Common Issues

Issue: “Pod CrashLoopBackOff”

# Check logs for error
kubectl logs -n sparki-dev deployment/backend

# Common causes:
# - Missing environment variable
# - Database connection failure
# - Unhandled exception in startup

Issue: “Connect refused on localhost:3000”

# Check service is running
docker ps | grep backend

# Check port forwarding
kubectl port-forward svc/backend 3000:3000

# Check service exists
kubectl get svc -n sparki-dev

Issue: “Database migration failed”

# Check migration status
go run ./cmd/migrate/main.go status

# Check migration logs
docker logs docker_backend_1 | grep migration

# Rollback
go run ./cmd/migrate/main.go down

Contributing to Sparki

Development Workflow

1. Fork Repository (First Time)

# Visit https://github.com/sparki/sparki-tools
# Click "Fork" button
# Clone your fork
git clone https://github.com/YOUR_USERNAME/sparki-tools.git
cd sparki-tools

# Add upstream remote
git remote add upstream https://github.com/sparki/sparki-tools.git

2. Create Feature Branch

# Sync with latest main
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/descriptive-name

3. Make Changes

# Edit files
vim backend/main.go
vim web/pages/index.tsx

# Test locally
npm run dev          # Frontend
go test ./...        # Backend
docker-compose up    # Full stack

# Run linters
npm run lint         # Frontend
go vet ./...         # Backend

4. Commit Code

# Stage changes
git add backend/main.go web/pages/index.tsx

# Commit with message
git commit -m "feat: add user profile endpoint

- Add GetUserProfile handler
- Add /api/v1/users/:id route
- Add comprehensive tests"

# Push to your fork
git push origin feature/descriptive-name

5. Create Pull Request

# Visit https://github.com/YOUR_USERNAME/sparki-tools
# Click "Create Pull Request"
# Fill in description and link to issue
# Request reviewers

6. Address Review Comments

# Make requested changes
vim backend/main.go

# Commit changes (no force push)
git commit -m "address: code review feedback"
git push origin feature/descriptive-name

# Conversation continues in PR

7. Merge

Once approved:

Maintainer merges pull request
CI/CD pipeline runs automatically
Code is deployed to staging
Once verified, promoted to production

Code Quality Standards

Golang Code

package main

// Comments explain what, not how
// Exported functions start with uppercase
func ExportedFunction() error {
    // Implementation
    return nil
}

// Private functions start with lowercase
func privateHelper() {
    // Implementation
}

// Error handling
if err != nil {
    return fmt.Errorf("context: %w", err)
}

// Tests follow convention
func TestExportedFunction(t *testing.T) {
    // Table-driven tests preferred
    tests := []struct {
        name string
        input string
        expected string
    }{
        {"basic case", "input", "output"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test code
        })
    }
}

TypeScript/React Code

// Components are functions with proper types
interface Props {
  title: string;
  onClick?: () => void;
}

export const Button: FC<Props> = ({ title, onCli ck }) => {
  return <button onClick={onClick}>{title}</button>;
};

// Tests use testing library
describe('Button', () => {
  it('renders with title', () => {
    render(<Button title="Click me" />);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });
});

// Use TypeScript strict mode (no `any`)
// Proper error handling
// ESLint + Prettier configured

Next Steps

Complete Development Setup
- Run verification script
- Confirm all tools installed
Understand Architecture
- Read architecture documentation
- Explore codebase structure
Start Contributing
- Pick “good first issue” from GitHub
- Follow contribution workflow
- Submit pull request
Join Community
- Slack: #sparki-dev
- Meetings: Weekly tech sync (Thursdays 10am)
- Discord: Community channel

Additional Resources

API Documentation: See docs/API.md
Architecture Decisions: See docs/ADR/
Runbooks: See docs/runbooks/
Code Examples: See examples/
Troubleshooting: See docs/troubleshooting.md

Get Help

Quick Questions: Slack #sparki-dev
Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Security Issues: security@sparki.io

Welcome to Sparki! Happy coding! 🚀

Getting Started

User Guides

Deployment & Operations

DevOps

API Reference

Architecture

Specifications

Monetization

Reports & Status

​Sparki Developer Getting Started Guide

​Table of Contents

​Quick Start

​What You’ll Need (5 minutes)

​Your First Deployment (5 minutes)

​View Local Dashboards (2 minutes)

​Development Environment Setup

​System Requirements

​Installation Steps

​1. Install Core Tools (macOS)

​2. Install Core Tools (Ubuntu)

​3. Configure AWS Credentials

​4. Setup Local Kubernetes (Docker Desktop)

​5. Setup kubeconfig for EKS (if connecting to existing cluster)

​Verification Checklist

​Project Architecture Overview

​High-Level Architecture

​Technology Stack

​Directory Structure

​Local Development Workflow

​Start Your Development Environment

​Option 1: Docker Compose (Simplest)

​Option 2: Local Kubernetes

​Develop Backend Service

​Develop Frontend

​Database Development

​Make Common Commands

​First Deployment

​Deploy to Development Environment (15 minutes)

​Step 1: Prepare Code

​Step 2: Build Images

​Step 3: Deploy via Terraform

​Step 4: Verify Deployment

​Deploy to Staging/Production

​Common Development Tasks

​Task: Add New API Endpoint

​Task: Modify Database Schema

​Task: Add Frontend Component

​Task: Configure New Infrastructure

​Debugging & Troubleshooting

​View Logs

​Debug Database Connection

​Debug Kubernetes Deployment

​Common Issues

​Contributing to Sparki

​Development Workflow

​1. Fork Repository (First Time)

​2. Create Feature Branch

​3. Make Changes

​4. Commit Code

​5. Create Pull Request

​6. Address Review Comments

​7. Merge

​Code Quality Standards

​Golang Code

​TypeScript/React Code

​Next Steps

​Additional Resources

​Get Help