Share Bite Backend

Share Bite is a Go backend monorepo organized as three HTTP services plus a dedicated migration binary. The repository combines a guest-facing API, an authentication service, shared infrastructure packages, SQL migrations, and Docker-based local development tooling.

The codebase is organized by domain and follows a layered flow from HTTP handlers to services and repositories.

Project Overview

The repository currently contains:

• A guest API for customer profile operations and guest-facing post endpoints
• An admin-auth API for registration, login, and refresh-token flows
• A business API entrypoint and database schema scaffold for future business-domain functionality
• A standalone migrator for applying PostgreSQL schema changes
• Docker Compose configuration for local PostgreSQL, pgAdmin, and an optional S3-compatible Garage stack

Main Features

• Multi-service backend layout with separate binaries for guest, auth, and business domains
• JWT-based authentication with access and refresh tokens
• Email/password registration and login with bcrypt password hashing
• Authenticated customer profile creation, update, and self-profile retrieval
• Public customer lookup by username
• PostgreSQL schema versioning with Goose migrations
• Shared middleware for request IDs, request logging, validation, and auth context extraction

Tech Stack

Category	Technologies confirmed in the repository
Backend language	Go 1.25
HTTP framework	Gin
Database	PostgreSQL
Query / data access	pgx/v5, handwritten SQL, scany/pgxscan
ORM	No ORM is used
API style	JSON over HTTP, REST-style routing
Validation	Gin binding + go-playground/validator/v10 with a custom validator wrapper
Authentication	JWT (golang-jwt/jwt/v5), bcrypt password hashing
Authorization	Auth middleware stores user ID and role in Gin context; role-check middleware scaffold is present
Configuration	caarlos0/env/v11, godotenv
Logging	Uber Zap
Migrations	Goose (pressly/goose/v3)
Containerization	Docker, Docker Compose, per-service Dockerfiles
Local tooling	pgAdmin, Garage S3-compatible object storage, Garage Web UI
API documentation tooling	No Swagger / OpenAPI tooling is present in the repository

Project Structure

.
├── cmd/
│   ├── admin-auth-api/   # auth service entrypoint
│   ├── business-api/     # business service entrypoint
│   ├── guest-api/        # guest service entrypoint
│   └── migrator/         # migration runner
├── internal/
│   ├── admin-auth/       # auth handlers, service, repository, DTOs
│   ├── business/         # business domain scaffold
│   ├── config/           # environment-based config loading
│   ├── guest/            # guest handlers, services, repositories, entities
│   └── middleware/       # auth middleware
├── pkg/
│   ├── database/         # DB abstractions and pgx-backed client
│   ├── jwt/              # token generation and parsing
│   ├── logger/           # Zap-based logging helpers
│   ├── middleware/       # request ID and request logging
│   └── validator/        # validation adapter and error formatting
├── migrations/           # Goose SQL migrations
├── docker/               # Dockerfiles and Compose definitions
├── docs/                 # placeholder folders for API, architecture, and ADR-style docs
├── scripts/              # local bootstrap scripts
├── .env.example
├── go.mod
└── Makefile

Setup and Installation

Prerequisites

• Go 1.25+
• Docker and Docker Compose
• GNU Make

Initial Setup

1. Create a local environment file:

   cp .env.example .env

2. Start PostgreSQL for local development:

   docker compose -f docker/compose.yaml up -d pg

3. Optionally start pgAdmin:

   docker compose -f docker/compose.yaml --profile tools up -d pgadmin

4. Apply database migrations:

   make migrate-up

The repository also includes docker/compose.apps.yaml and per-service Dockerfiles if you want to run the APIs in containers instead of directly with go run.

Environment Variables

The project loads configuration from .env in local development. The .env.example file defines the variables below.

Variable(s)	Purpose
GUEST_HTTP_SERVER_HOST, GUEST_HTTP_SERVER_PORT	Guest API bind address
ADMIN_HTTP_SERVER_HOST, ADMIN_HTTP_SERVER_PORT	Admin auth API bind address
BUSINESS_HTTP_SERVER_HOST, BUSINESS_HTTP_SERVER_PORT	Business API bind address
POSTGRES_HOST, POSTGRES_PORT, POSTGRES_SSL, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	PostgreSQL connection settings
POSTGRES_MIGRATIONS_DIR	Path used by the built-in migration runner
JWT_ACCESS_TOKEN_SECRET_KEY, JWT_REFRESH_TOKEN_SECRET_KEY	Secrets used to sign JWTs
JWT_ACCESS_TOKEN_TTL, JWT_REFRESH_TOKEN_TTL	Access and refresh token lifetimes
APP_NAME, APP_STAGE, APP_GRACEFUL_SHUTDOWN_TIMEOUT	Application metadata and shutdown behavior
PGADMIN_PORT, PGADMIN_EMAIL, PGADMIN_PASSWORD	Optional pgAdmin container settings
GOOSE_DRIVER, GOOSE_DBSTRING, GOOSE_MIGRATION_DIR	Optional Goose CLI helper variables included in the template

Notes:

• Use POSTGRES_HOST=localhost when running the Go binaries directly on your machine.
• Use POSTGRES_HOST=pg only when the application itself runs inside Docker containers on the Compose network.

Running the Project Locally

Start all three services:

make run-all

Run services individually if needed:

make run-guest
make run-auth
make run-business

Default ports from .env.example:

• Guest API: http://localhost:3800
• Admin Auth API: http://localhost:3850
• Business API: http://localhost:3900

Migrations and Seed Data

Run migrations with either of the following commands:

make migrate-up

go run cmd/migrator/main.go

• SQL migrations are stored in migrations/
• Goose is used as the migration engine
• No seeders or seed scripts are present in the current repository

API Documentation

The repository does not include Swagger, OpenAPI, Redoc, or other generated API documentation artifacts. The docs/ directory currently contains placeholder folders only.

Current route surface from the codebase:

Admin Auth API

• POST /auth/register
• POST /auth/login
• POST /auth/refresh

Guest API

• GET /customers/:username
• POST /customers
• PATCH /customers
• GET /customers
• GET /posts
• GET /posts/:id

Protected customer endpoints require an Authorization: Bearer <access_token> header.

Business API

• A separate business service binary exists, but no HTTP routes are currently registered in internal/business/handler/business

Optional Local Object Storage

The repository also contains a local Garage setup for S3-compatible development.

Start and bootstrap Garage:

make s3-up

Start the Garage Web UI:

make s3-ui

Current code status:

• Garage is included as local infrastructure
• Customer avatar URL generation is still a placeholder in the guest handler layer
• The Go services do not yet contain active S3 client integration

Architecture Notes

• The codebase follows a layered backend structure: handler -> service -> repository -> database
• Domain code is separated under internal/admin-auth, internal/guest, and internal/business
• Cross-cutting concerns are extracted into reusable pkg/ modules
• PostgreSQL schemas mirror domain boundaries: auth, guest, and business
• Authentication is centralized in the auth service, while protected guest endpoints consume JWT access tokens through middleware

Current implementation notes inferred from the code:

• Customer profile functionality is the most complete feature area in the repository
• Guest post endpoints are present, but the repository logic is still scaffolded and currently returns placeholder data / not-found behavior
• The business service and schema are scaffolded, but the HTTP layer has not been implemented yet