Skip to content

Getting Started

This tutorial walks you through setting up a development environment for the Wippidu Kita App and running it locally.

Prerequisites

Tool Version Check
Go 1.24.0+ go version
Git 2.x git --version
SQLite3 3.x sqlite3 --version
Make any make --version

The application uses SQLite for development and testing. PostgreSQL or MySQL is used in production but not required for local development.

Clone and build

# Clone the repository
git clone <repo-url> wippidu-app
cd wippidu-app

# Navigate to the backend
cd backend

# Download dependencies
go mod download

# Build the application
make build

Run the application

cd backend
go run cmd/app-server/main.go

The server starts on http://localhost:8080 in debug mode. On first run it automatically initializes test data:

  • 2 locations (Alpha, Beta)
  • 5 groups (The Bees, The Butterflies, The Ladybugs, The Dolphins, The Turtles)
  • 50 children (10 per group)
  • 44 parent accounts
  • 7+ employee accounts
  • 1 admin account

Log in with one of these test accounts:

Role Email Password
Parent (3 children) emma.mueller@wippidu.app password123
Group Leader teacher.bees@wippidu.app teacher123
Location Leader teacher.alpha@wippidu.app teacher123
Admin admin@wippidu.app adminsecret

See Test Accounts for the full list.

Run the tests

cd backend

# Run all tests
make test

# Run with verbose output
make test-verbose

# Run a specific package
go test ./internal/controller/... -v

# Run a single test
go test ./internal/controller -run TestLogin -v

The test suite currently contains 950 test functions across 63 test files. Tests use an in-memory SQLite database and require no external services.

See How to Run Tests for all available test targets.

Project structure

backend/
├── cmd/
│   ├── app-server/           # Main application
│   │   ├── main.go           # Entry point
│   │   ├── templates/        # 106 HTML templates
│   │   │   ├── layouts/      # Base layouts
│   │   │   ├── includes/     # Shared partials
│   │   │   └── pages/        # Page templates
│   │   └── static/           # CSS, JS, images
│   └── init-testdata/        # Manual test data init
├── internal/
│   ├── controller/           # 44 controller files (HTTP handlers)
│   ├── service/              # 23 service files (business logic)
│   ├── model/                # GORM models and database
│   ├── middleware/            # 7 middleware files
│   │   ├── authorization.go  # JWT auth middleware
│   │   ├── api_token.go      # Bearer token auth
│   │   ├── force_password_change.go
│   │   ├── language.go       # i18n language detection
│   │   ├── ratelimit.go      # Rate limiting
│   │   └── require_approval.go
│   ├── route/                # Route definitions
│   │   ├── auth.go           # HTML + API routes
│   │   └── intranet.go       # Intranet sync API routes
│   └── i18n/                 # Internationalization
│       └── locales/          # de.json, en.json
├── Makefile                  # Build and test targets
└── go.mod                    # Go 1.24.0

Key patterns

Dual HTML/JSON responses: Every controller uses shouldReturnJSON(c) to serve both HTML templates and JSON API responses from the same handler:

func MyHandler(c *gin.Context) {
    isJSON := shouldReturnJSON(c)
    // ... business logic ...
    if isJSON {
        c.JSON(http.StatusOK, gin.H{"success": true, "data": result})
        return
    }
    c.HTML(http.StatusOK, "my-template.html", gin.H{"data": result})
}

i18n translations: Templates use {{ t .lang "key" }} for translated strings. Translation files are in internal/i18n/locales/{de,en}.json.

Role-based access: Six roles control access: Anonymous, Parent, Employee, GroupLead, LocationLead, Admin. See Authorization Model.

Next steps