Development

This guide covers the local BoxBox development workflow.

Prerequisites

• Go 1.24+
• Bun 1.1+
• Node.js 22+ for Svelte tooling compatibility
• air for backend hot reload:

go install github.com/air-verse/air@latest

Make sure $GOPATH/bin is on your PATH.

Repository Layout

backend/      Go API server and embedded static host
frontend/     SvelteKit app compiled to static files
docs/         Markdown project documentation
scripts/      Local development helpers
Dockerfile    Single-container production build

Install Dependencies

bun install --cwd frontend
cd backend && go mod download

Run the Product App

From the repository root:

bun run dev

This starts:

• SvelteKit frontend through Vite.
• Go backend through air -c backend/.air.toml.

The backend uses backend/config.yaml. For a safer local setup, edit that file to point at temporary directories instead of broad host paths:

mkdir -p /tmp/boxbox/media /tmp/boxbox/documents

mount_points:
  - name: "media"
    path: "/tmp/boxbox/media"
    read_only: false
  - name: "documents"
    path: "/tmp/boxbox/documents"
    read_only: false

Run Pieces Separately

Backend:

cd backend
go run ./cmd/server -config config.yaml

Frontend:

bun run --cwd frontend dev

Build

Frontend app:

bun run --cwd frontend build

Production container:

docker build -t boxbox:local .

The Dockerfile builds the frontend first, copies frontend/build into backend/internal/static/dist, and compiles the Go server with embedded assets.

Test and Validate

Backend:

cd backend
go test ./...

Frontend checks:

bun run --cwd frontend check
bun run --cwd frontend build

Backend Patterns

Use the existing Handler -> Service -> Model/Filesystem shape:

• Handlers parse requests and write responses.
• Services own business logic and filesystem work.
• Models define request, response, and domain types.
• Shared constants belong in backend/internal/config/constants.go.
• File operations should go through internal/pkg/filesystem and existing validators.

Frontend Patterns

• Use Svelte 5 patterns already present in the repo.
• API calls belong in frontend/src/lib/api.
• Shared UI primitives belong in frontend/src/lib/components/ui.
• Formatting belongs in frontend/src/lib/utils/format.ts.
• File type logic belongs in frontend/src/lib/utils/fileTypes.ts.
• Central config belongs in frontend/src/lib/config.ts.