API Backend (Go)

Introduction

The api-backend is a lightweight Go server that can handle the shared mobile resource contract when the gateway routes /api/v1/app/* to Go performance mode. Once Sanctum middleware is implemented (BR-500), it will validate Laravel Sanctum Personal Access Tokens by reading the personal_access_tokens table directly.

Foundation (Available Now)

The foundation template provides:

• Health endpoint — GET /health returns service status.
• Typed config — Environment-based configuration for app, DB, Redis, CORS, body limits, and Laravel URL.
• DB connection — MySQL/MariaDB connection layer.
• Router — Chi-based HTTP router with graceful shutdown.
• Response/Error envelope — JSON success/error format matching Laravel API style.
• Dockerfile and compose — Ready for local development and container deployment.

Shared Mobile Contract

Once subsequent phases are complete, the api-backend can serve these shared routes when /api/v1/app/* points at Go performance mode:

• Authenticated User Endpoints: GET /api/v1/app/me, POST /api/v1/app/device-tokens, PUT /api/v1/app/users/{uuid}.
• Security Reads: GET /api/v1/app/security/authlogs, GET /api/v1/app/security/sessions.
• Help Center: Mobile-facing reads for FAQs, contacts, and operating hours.
• Feedback: Store and list with validation, spam prevention, and rate limiting.
• Notifications: Full CRUD plus send and broadcast endpoints.
• Preferences: User and notification preference show/update.
• Billing: GET /api/v1/app/billing/entitlements.

Directory Structure (Foundation)

The current foundation layout matches what the template generates:

api-backend/
├── cmd/
│   └── api/
│       ├── main.go              # Entry point + bootstrap
│       └── main_test.go
├── internal/
│   ├── config/                  # Typed env configuration
│   │   ├── config.go
│   │   └── config_test.go
│   ├── db/                      # MySQL/MariaDB connection layer
│   │   ├── db.go
│   │   └── db_test.go
│   ├── health/                  # Health endpoint handler
│   │   ├── health.go
│   │   └── health_test.go
│   ├── http/
│   │   ├── errors/              # Error envelope helpers
│   │   │   ├── errors.go
│   │   │   └── errors_test.go
│   │   └── response/            # Success response helpers
│   │       ├── response.go
│   │       └── response_test.go
│   ├── router/                  # Chi router + route registration
│   │   ├── router.go
│   │   └── router_test.go
│   └── server/                  # Server lifecycle + graceful shutdown
│       ├── server.go
│       └── server_test.go
├── .env.example
├── Dockerfile
├── compose.dev.yaml
├── go.mod
├── go.sum
└── README.md

Additional packages for middleware, handlers, models, and services will be added in subsequent phases (BR-500 through BR-800).

Getting Started

1. Requirements

• Go 1.26+ (version specified in go.mod)
• MySQL/MariaDB (shared with admin-panel)

2. Setup

Navigate to api-backend/ and run:

cp .env.example .env
# Edit .env with your database connection and Laravel URL
go mod tidy
go run cmd/api/main.go

The server starts on http://localhost:8080 with a GET /health endpoint.

Authentication (Planned)

Once implemented, the Go api-backend will validate Sanctum Personal Access Tokens using the same database as the Laravel admin-panel:

1. Extract Bearer token from the Authorization header.
2. SHA-256 hash the token.
3. Look up the hash in the personal_access_tokens table.
4. Verify the token has not expired and has the required abilities.
5. Populate the request context with the authenticated user.

This means tokens issued by the Laravel admin-panel will be immediately valid on the Go api-backend with no additional configuration.

Shared Route Set (Planned)

The following routes are planned for the api-backend after middleware and endpoint phases are complete. The same /api/v1/app/* routes exist in Laravel compatibility mode as well.

Response Format

The foundation already implements the same JSON structure as the Laravel admin-panel:

{
  "success": true,
  "message": "Optional success message",
  "data": { ... }
}

Error responses follow the same format with standard HTTP status codes (401, 422, 429).

Testing

go test ./...

Next Steps

After both services are running, see the Docker Deployment Guide for canonical Caddy prefix routing. Production rollout still requires the Go service to be present in the production compose/deployment stack.