Skip to content

getting-started.md

Latest commit

 

History

History
331 lines (221 loc) · 5.31 KB

getting-started.md

File metadata and controls

331 lines (221 loc) · 5.31 KB

Quick Reference

Last Updated: 2025-11-05

Quick reference for common commands, operations, and configurations.

Table of Contents

Quick Start

First-Time Setup

# Clone repository
git clone https://github.com/rastrigin-systems/arfa.git
cd arfa

# Start database
make db-up

# Install tools (one-time)
make install-tools

# Generate all code
make generate

# Run tests
make test

# View documentation
open docs/database/schema-reference.md

Run make to see all available commands.

Database Commands

Basic Operations

# Start PostgreSQL
make db-up

# Stop PostgreSQL
make db-down

# Reset database (⚠️ deletes all data)
make db-reset

# Run migrations
make db-migrate

# Rollback migrations
make db-rollback

Database Access

# PostgreSQL connection string
postgres://arfa:arfa_dev_password@localhost:5432/arfa

# Adminer web UI
open http://localhost:8080

# psql CLI
docker exec -it arfa-postgres psql -U arfa -d arfa

# Direct SQL query
docker exec arfa-postgres psql -U arfa -d arfa -c "SELECT COUNT(*) FROM employees"

Common Queries

# List all tables
docker exec arfa-postgres psql -U arfa -d arfa -c "\dt"

# Describe table structure
docker exec arfa-postgres psql -U arfa -d arfa -c "\d employees"

# Count records in table
docker exec arfa-postgres psql -U arfa -d arfa -c "SELECT COUNT(*) FROM organizations"

# View all organizations
docker exec arfa-postgres psql -U arfa -d arfa -c "SELECT id, name, created_at FROM organizations"

# Check migrations status
docker exec arfa-postgres psql -U arfa -d arfa -c "SELECT version, dirty FROM schema_migrations"

See Database documentation for complete guide.

Code Generation

Setup

# Install code generation tools (one-time)
make install-tools

Generate Code

# Generate everything (ERD + API + DB + Mocks)
make generate

# Generate ERD docs only
make generate-erd

# Generate API code only
make generate-api

# Generate DB code only
make generate-db

# Generate mocks only
make generate-mocks

When to Regenerate

Manual:

# After changing platform/database/schema.sql
make db-reset && make generate-db && make generate-mocks

# After changing platform/api-spec/spec.yaml
make generate-api

# After changing SQL queries
make generate-db && make generate-mocks

# After changing interfaces (for mocks)
make generate-mocks

# Or regenerate everything
make generate

Testing

Run Tests

# Run all tests with coverage
make test

# Run unit tests only (fast, no Docker required)
make test-unit

# Run integration tests only (requires Docker)
make test-integration

# Generate HTML coverage report
make test-coverage

# Open coverage report
open coverage.html

Test Specific Package

# Test single package
go test ./services/api/internal/handlers/...

# Test with verbose output
go test -v ./services/api/internal/handlers/...

# Test with coverage
go test -cover ./services/api/internal/handlers/...

# Test specific function
go test -run TestCreateEmployee ./services/api/internal/handlers/...

See Testing guide for complete guide.

Development

Build Binaries

# Build everything
make build

# Build API server
cd services/api && go build -o ../../bin/arfa-api ./cmd/server

# Build CLI
cd services/cli && go build -o ../../bin/arfa ./cmd/arfa-cli

# Build with specific tags
go build -tags integration -o bin/arfa-test ./services/cli/cmd/arfa-cli

Run Services

# Start all services with docker compose
make dev

# Run API server manually
./bin/arfa-api

# Run CLI manually
./bin/arfa-cli <command>

Clean Build Artifacts

# Clean generated files and binaries
make clean

# Clean Docker volumes
docker volume prune

# Clean Go build cache
go clean -cache

# Remove test databases
docker rm -f $(docker ps -aq --filter "name=postgres")

See PR Workflow for complete workflow.

Common Tasks

Update Dependencies

# Update Go dependencies
go get -u ./...
go mod tidy

# Update specific dependency
go get -u github.com/org/package@latest

# Sync go.work
go work sync

View Logs

# API server logs
tail -f logs/api.log

# CLI logs
tail -f ~/.arfa/logs/cli.log

# Docker container logs
docker logs arfa-postgres -f
docker logs arfa-api -f

Environment Variables

# View all env vars
env | grep ARFA

# Set env var for session
export ARFA_API_URL=http://localhost:8080

# Set env var permanently (add to ~/.zshrc or ~/.bashrc)
echo 'export ARFA_API_URL=http://localhost:8080' >> ~/.zshrc
source ~/.zshrc

Make

# Show all available make targets
make help

# Run target with verbose output
make <target> VERBOSE=1

See Also