Skip to main content

Getting Started

Welcome to Solverhood! This guide will help you set up your development environment and get started with our technology stack.

🛠️ Prerequisites​

Before you begin, ensure you have the following installed:

Required Software​

  • VS Code with recommended extensions
  • Postman or Insomnia for API testing
  • DBeaver or pgAdmin for database management

🚀 Quick Setup​

1. Clone the Repository​

git clone https://github.com/solverhood/tech-docs.git
cd tech-docs

2. Install Dependencies​

# Install Node.js dependencies
pnpm install

# Install Go dependencies (if working on backend)
go mod download

3. Environment Configuration​

# Copy environment template
cp .env.example .env

# Edit with your local settings
nano .env

4. Start Development Services​

# Start all services with Docker Compose
docker-compose up -d

# Or start individual services
docker-compose up postgres redis clickhouse -d

📋 Development Environment Setup​

Backend Development (Go)​

Install Go Tools​

# Install required Go tools
go install github.com/99designs/gqlgen@latest
go install entgo.io/ent/cmd/ent@latest
go install ariga.io/atlas/cmd/atlas@latest
go install github.com/cosmtrek/air@latest
go install github.com/nats-io/natscli/nats@latest

Install Apple Pkl​

# Install Pkl engine
curl -L -o pkl https://github.com/apple/pkl/releases/download/0.25.3/pkl-alpine-linux-amd64
chmod +x pkl
sudo mv pkl /usr/local/bin

# Install Pkl Go generator
curl -L -o pkl-gen-go https://github.com/apple/pkl-go/releases/download/v0.6.0/pkl-gen-go-linux-amd64.bin
chmod +x pkl-gen-go
sudo mv pkl-gen-go /usr/local/bin

Install Taskfile​

# Install Taskfile for task automation
go install github.com/go-task/task/v3/cmd/task@latest

Frontend Development (React/TypeScript)​

Install Node.js Tools​

# Install Biome for code formatting
pnpm add -g @biomejs/biome

# Install TypeScript globally
pnpm add -g typescript

# Install development tools
pnpm add -g concurrently nodemon

VS Code Extensions​

Install these recommended extensions:

  • TypeScript and JavaScript Language Features
  • ES7+ React/Redux/React-Native snippets
  • Tailwind CSS IntelliSense
  • Biomejs - Code formatter
  • GitLens

🗄️ Database Setup​

PostgreSQL (OLTP)​

# Start PostgreSQL
docker-compose up postgres -d

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

# Run migrations
atlas migrate apply --url "postgres://postgres:password@localhost:5432/solverhood?sslmode=disable"

ClickHouse (OLAP)​

# Start ClickHouse
docker-compose up clickhouse -d

# Connect to ClickHouse
clickhouse-client --host localhost --port 9000 --user default --password

🔧 Configuration​

Environment Variables​

Create a .env file with the following variables:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=solverhood

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DB=solverhood

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# AWS (for production)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
AWS_S3_BUCKET=your_bucket_name

# NATS
NATS_URL=nats://localhost:4222

# Application
APP_ENV=development
APP_PORT=8080
APP_SECRET=your_secret_key

IDE Configuration​

VS Code Settings​

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.preferences.importModuleSpecifier": "relative",
  "go.useLanguageServer": true,
  "go.toolsManagement.autoUpdate": true
}

VS Code Extensions​

Create .vscode/extensions.json:

{
  "recommendations": [
    "golang.go",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-json"
  ]
}

🧪 Testing Your Setup​

Backend Tests​

# Run Go tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test
go test ./internal/handlers -v

Frontend Tests​

# Run TypeScript/React tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run specific test file
pnpm test -- src/components/Button.test.tsx

Integration Tests​

# Run integration tests
pnpm test:integration

# Run E2E tests
pnpm test:e2e

🚀 Running the Application​

Development Mode​

# Backend (with hot reload)
air

# Frontend (with hot reload)
pnpm dev

# Both simultaneously
pnpm dev:full

Production Build​

# Build frontend
pnpm build

# Build backend
go build -o bin/server ./cmd/server

# Run with Docker
docker-compose up --build

📚 Next Steps​

  1. Read the Architecture Overview to understand our system design
  2. Review Coding Standards to maintain code quality
  3. Explore API Documentation to understand our services
  4. Check out Best Practices for development patterns

🆘 Troubleshooting​

Common Issues​

Port Already in Use​

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

Database Connection Issues​

# Check if PostgreSQL is running
docker-compose ps

# Restart services
docker-compose restart postgres

Go Module Issues​

# Clean module cache
go clean -modcache

# Download dependencies
go mod download

Node.js Issues​

# Clear cache
pnpm store prune

# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

📞 Getting Help​

  • Documentation Issues: Create a GitHub issue in this repository
  • Technical Questions: Reach out to the development team
  • Setup Problems: Check our Troubleshooting Guide

Ready to start coding? Check out our First Project Guide to build your first feature!