Group Manager

REST API service for managing hierarchical groups of people with recursive member counting.

Features

• Group management – create, update, and delete groups with a tree-like hierarchy (parent/child relationships)
• People management – create, update, and delete people (first name, last name, birth year); assign to a group on creation, change group on update
• Group listing with member counts – list all groups with direct_count (members directly in the group) and total_count (members including all descendant groups) via recursive CTE
• Group members listing – list members of a specific group, optionally including members from all descendant groups (?deep=true)

Architecture

Clean Architecture with dependency injection:

• entity – domain models
• usecase – business logic
• infra/postgres – data access layer
• delivery/http – HTTP handlers

Setup

1. Clone the repository:

   git clone <repo-url>
   cd group-manager

2. Environment configuration (.env.example file already contains default values):

   POSTGRES_DB=group_manager
   POSTGRES_USER=group_manager
   POSTGRES_PASSWORD=supersecret

3. Application configuration (config/config.yaml):

   http:
     host: "0.0.0.0"
     port: 50000
   postgres:
     conn_string: "host=localhost port=5432 user=group_manager password=supersecret dbname=group_manager sslmode=disable"
   snowflake:
     node_id: 1

Connection Details

PostgreSQL

Parameter	Value
Host	localhost
Port	5432
Database	group_manager
User	group_manager
Password	supersecret
Connection string	postgres://group_manager:supersecret@localhost:5432/group_manager?sslmode=disable

API

Parameter	Value
Host	http://localhost
Port	50000
Base path	/v1

Running the Project

Quick Start (Docker Compose)

# Start PostgreSQL + API + migrations
just up

# Check status
just status

# View logs
just logs

Manual Start

# 1. Start PostgreSQL
docker compose -f deploy/compose.yaml -p group_manager --env-file .env up -d postgres

# 2. Apply migrations
goose -dir migrations up

# 3. Start API
go run ./cmd/api

Stop

just down

Available Commands (Justfile)

Command	Description
just up	Start all services
just down	Stop all services
just restart	Restart services
just logs	View service logs
just status	Check service status
just postgres	Connect to psql
just sqlc	Regenerate sqlc code

API Examples

# Create a group
curl -X POST http://localhost:50000/v1/groups \
  -H "Content-Type: application/json" \
  -d '{"name":"Backend","parent_id":null}'

# Create a person
curl -X POST http://localhost:50000/v1/people \
  -H "Content-Type: application/json" \
  -d '{"group_id":1,"firstname":"John","lastname":"Doe","birthday":"1990-01-15"}'

# List groups with member counts
curl http://localhost:50000/v1/groups

# List group members (with descendants)
curl "http://localhost:50000/v1/groups/1/members?deep=true"

# Delete a person (returns deleted person ID)
curl -X DELETE http://localhost:50000/v1/people/1

# Delete a group and all its descendants (returns deleted group IDs)
curl -X DELETE http://localhost:50000/v1/groups/1