SkillSpark 🎯

SkillSpark is a unified platform for students in Thailand to discover and engage with diverse activities and experiences. We're building a product that gives people the chance to explore and easily access all the learning opportunities this country has to offer—a platform to spark their curiosity and develop new skills!

Tech Stack

Backend

Framework: Fiber (Express-inspired web framework for Go)
Language: Go 1.22
Linting: golangci-lint v1.64.8
Testing: Go's built-in testing framework with coverage reporting

Frontend

Framework: React 18
Build Tool: Vite
Language: TypeScript
Package Manager: Bun
Linting: ESLint

Database

Database: PostgreSQL (hosted on Supabase)
CLI: Supabase CLI for migrations and local development

DevOps

CI/CD: GitHub Actions
Containerization: Docker
Orchestration: Docker Compose with hot reload
Deployment: Digital Ocean (coming soon)

Prerequisites

Before you begin, ensure you have the following installed:

Go 1.22 or higher - Download
Bun (latest) - Download
Docker and Docker Compose - Download
golangci-lint v1.64.8 - Installation
Supabase CLI - Installation
Make - Usually pre-installed on macOS/Linux, Windows installation

macOS Installation

# Install Go
brew install go

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install Docker
brew install --cask docker

# Install golangci-lint
brew install golangci-lint

# Install Supabase CLI
brew install supabase/tap/supabase

Windows Installation

# Install Bun (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Install other tools via their respective installers

Getting Started

Quick Start (Recommended - Using Docker)

# Clone the repository
git clone <your-repo-url>
cd skillspark

# Start all services with hot reload
make up

This will start:

Frontend at http://localhost (Vite dev server with hot reload)
Backend at http://localhost:8080 (Fiber server with hot reload)

Other useful commands:

make down      # Stop all services
make logs      # View logs from all services
make restart   # Restart all services
make help      # See all available commands

Manual Setup (Without Docker)

1. Environment Setup

Backend Environment Variables Create a .env file in the backend/ directory based off the template

Frontend Environment Variables Create a .env file in the frontend/ directory based off the template

2. Database Setup (Supabase)

cd backend

# Start local Supabase (requires Docker)
make db-start

# Create a new migration (if needed)
make db-new NAME=initial_schema

# Reset database and apply migrations
make db-reset

Local Supabase URLs:

Dashboard: http://localhost:54323
Database: postgresql://postgres:postgres@127.0.0.1:54322/postgres

Link to Remote Supabase (Production):

# Find your project ref in Supabase dashboard URL
make db-link REF=your-project-ref

# Push migrations to remote
make db-push

3. Backend Setup

cd backend

# Install dependencies
make download

# Run tests
make test

# Start development server
make dev

Backend will start at http://localhost:8080

4. Frontend Setup

cd frontend

# Install dependencies
make install

# Start development server
make dev

Frontend will start at http://localhost:5173

Development Workflow

Using Makefiles

This project uses Makefiles for streamlined development. Run make help in any directory to see available commands.

Root Directory Commands

make help              # Show all available commands
make up                # Start all services with Docker
make down              # Stop all services
make logs              # View logs from all services
make up-backend        # Start only backend
make up-frontend       # Start only frontend
make build             # Build all services
make clean             # Remove containers and volumes

Backend Commands (cd backend)

# Development
make dev               # Start development server
make build             # Build the application

# Testing
make test              # Run all tests
make test-coverage     # Run tests with coverage report
make test-one TEST=TestName  # Run specific test

# Code Quality
make lint              # Run golangci-lint
make lint-fix          # Fix linting issues
make format            # Format code with gofmt

# Database
make db-start          # Start local Supabase
make db-stop           # Stop local Supabase
make db-reset          # Reset DB and apply migrations
make db-new NAME=...   # Create new migration
make db-status         # Show DB status

# API Documentation
make api-gen           # Generate OpenAPI spec
make api-preview       # Preview API docs at /docs

# Dependencies
make tidy              # Run go mod tidy
make deps              # Update all dependencies

Frontend Commands (cd frontend)

# Development
make dev               # Start Vite dev server
make build             # Build for production
make preview           # Preview production build

# Code Quality
make type-check        # Run TypeScript checking
make lint              # Run ESLint
make lint-fix          # Fix ESLint issues
make format            # Format with Prettier
make format-check      # Check formatting
make check             # Run all checks
make fix               # Fix all issues

# Dependencies
make install           # Install dependencies with Bun
make deps              # Update dependencies
make tidy              # Clean and reinstall

# Analysis
make analyze           # Analyze bundle size
make size              # Check bundle size

Pre-commit Hooks

This project uses Husky for pre-commit hooks that automatically:

Format Go code with gofmt
Run golangci-lint on Go files
Run ESLint on frontend files
Tidy Go modules

Setup hooks:

# From root directory
make setup-hooks

Or install manually:

cd frontend
bun install  # Installs husky automatically

Hot Reload in Docker

Docker Compose is configured with hot reload for both services:

Backend: Uses Air for Go hot reload
Frontend: Vite's built-in HMR

Changes to your code will automatically trigger rebuilds!

Note for Windows users: Hot reload uses docker watch. If make up doesn't enable it automatically, run docker watch in a separate terminal.

Testing

Backend Tests

cd backend

# Run all tests
make test

# Run with coverage (70% minimum recommended)
make test-coverage

# Run specific test
make test-one TEST=TestActivityHandler

# Run only unit tests
make test-unit

# Run database tests
make test-db

# Clean test cache
make test-clean

Frontend Tests

cd frontend

# Run tests (if configured)
bun test

Code Quality

Running All Checks

Backend:

cd backend
make lint && make format-check && make test

Frontend:

cd frontend
make check  # Runs type-check, lint, and format-check

Auto-fixing Issues

Backend:

cd backend
make lint-fix && make format

Frontend:

cd frontend
make fix  # Runs lint-fix and format

Repository Structure

skillspark/
├── backend/              # Go Fiber backend service
│   ├── cmd/
│   │   ├── main.go      # Application entry point
│   │   └── genapi/      # OpenAPI spec generator
│   ├── internal/        # Private application code
│   │   ├── handlers/   # HTTP request handlers
│   │   ├── models/     # Data models
│   │   ├── services/   # Business logic
│   │   ├── storage/    # Database layer
│   │   └── supabase/   # Supabase migrations
│   ├── api/            # OpenAPI specifications
│   ├── Makefile        # Backend commands
│   └── go.mod          # Go dependencies
├── frontend/            # React + Vite frontend
│   ├── src/
│   │   ├── components/ # React components
│   │   ├── pages/      # Page components
│   │   ├── hooks/      # Custom React hooks
│   │   ├── utils/      # Utility functions
│   │   └── api/        # API client
│   ├── public/         # Static assets
│   ├── Makefile        # Frontend commands
│   ├── vite.config.ts  # Vite configuration
│   └── package.json    # Dependencies and scripts
├── docs/               # Documentation
├── .github/
│   └── workflows/      # CI/CD pipelines
├── .husky/             # Git hooks
├── scripts/            # Utility scripts
├── docker-compose.yml  # Service orchestration
├── .golangci.yml       # Linting configuration
├── Makefile            # Root-level commands
└── README.md

CI/CD Pipeline

Our GitHub Actions workflows automatically run on every pull request:

Backend Checks (`.github/workflows/backend.yaml`)

✅ Path filtering (only runs when backend files change)
✅ Linting with golangci-lint
✅ Unit and integration tests
✅ Coverage reporting (70% minimum recommended)
✅ Test result summaries posted to PRs
✅ Coverage reports uploaded as artifacts

Triggers

Pull requests to main branch
Only runs when respective backend or frontend files are modified

Coverage Enforcement

Minimum coverage threshold: 70%
Coverage reports are generated and posted to PRs
Tests must pass for PR to be mergeable

API Documentation

The backend API is built with Go Fiber and includes OpenAPI documentation.

Accessing API Docs

# Generate OpenAPI spec
cd backend
make api-gen

# Start the server and view docs
make dev

# Open browser to:
http://localhost:8080/docs

Example Endpoints

GET    /api/v1/activities       # List all activities
GET    /api/v1/activities/:id   # Get activity by ID
POST   /api/v1/activities       # Create new activity
PUT    /api/v1/activities/:id   # Update activity
DELETE /api/v1/activities/:id   # Delete activity

Docker

Development with Docker Compose

# Start all services
make up

# Start individual services
make up-backend
make up-frontend

# View logs
make logs
make logs-backend
make logs-frontend

# Restart services
make restart

# Stop services
make down

# Clean everything (including volumes)
make clean

Production Builds

# Build images
make build

# Or build individually
make build-backend
make build-frontend

# Rebuild without cache
make rebuild

Container Management

# Open shell in container
make shell-backend
make shell-frontend

# View running containers
make ps

# Clean Docker resources
make prune

Deployment

🚧 Deployment to Digital Ocean is coming soon!

Contributing

Create a feature branch from main

   git checkout -b feature/your-feature-name

Make your changes
- Follow the style guides in docs/
- Write tests for new features
- Ensure code passes all checks
Run checks locally

   # Backend
   cd backend && make lint && make test
   
   # Frontend  
   cd frontend && make check

Commit your changes
- Pre-commit hooks will run automatically
- Fix any issues before committing
Push and create a pull request

   git push origin feature/your-feature-name

Wait for CI checks and code review

Branch Naming Convention

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation updates
refactor/ - Code refactoring
test/ - Test additions or modifications

Troubleshooting

Docker Issues

Port already in use:

# Check what's using the port
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Kill the process or change port in docker-compose.yml

Docker not starting:

# Make sure Docker Desktop is running
docker info

# Restart Docker if needed

Hot reload not working:

# Windows users: run docker watch in separate terminal
docker watch

# Or restart containers
make restart

Backend Issues

Database connection failed:

# Check Supabase is running
make db-status

# Restart Supabase
make db-stop && make db-start

# Check .env file has correct credentials

Tests failing:

# Clean test cache
make test-clean

# Run tests again
make test

golangci-lint version mismatch:

# Install specific version
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8

Frontend Issues

Module not found:

cd frontend
make tidy  # Clean and reinstall

Build fails:

# Clear Bun cache
rm -rf node_modules bun.lockb
make install

API calls failing:

# Check backend is running
curl http://localhost:8080/health

# Verify VITE_API_URL in .env

Bun issues:

# Update Bun
bun upgrade

# Clear Bun cache
bun pm cache rm

Common Make Command Issues

Make not found (Windows):

Install Make from GnuWin32
Or use Git Bash which includes Make

Permission denied:

# macOS/Linux: Make scripts executable
chmod +x scripts/*.sh

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
.husky		.husky
backend		backend
docs		docs
frontend/web		frontend/web
scripts/hooks		scripts/hooks
.env.template		.env.template
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

License

GenerateNU/skillspark

Folders and files

Latest commit

History

Repository files navigation

SkillSpark 🎯

Tech Stack

Backend

Frontend

Database

DevOps

Prerequisites

macOS Installation

Windows Installation

Getting Started

Quick Start (Recommended - Using Docker)

Manual Setup (Without Docker)

1. Environment Setup

2. Database Setup (Supabase)

3. Backend Setup

4. Frontend Setup

Development Workflow

Using Makefiles

Root Directory Commands

Backend Commands (cd backend)

Frontend Commands (cd frontend)

Pre-commit Hooks

Hot Reload in Docker

Testing

Backend Tests

Frontend Tests

Code Quality

Running All Checks

Auto-fixing Issues

Repository Structure

CI/CD Pipeline

Backend Checks (.github/workflows/backend.yaml)

Triggers

Coverage Enforcement

API Documentation

Accessing API Docs

Example Endpoints

Docker

Development with Docker Compose

Production Builds

Container Management

Deployment

Contributing

Branch Naming Convention

Troubleshooting

Docker Issues

Backend Issues

Frontend Issues

Common Make Command Issues

Useful Resources

Team

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Backend Checks (`.github/workflows/backend.yaml`)

Packages