How hashednode/snowflaker works
Project Type and Purpose
– Snowflaker is a single-purpose micro-backend service (no UI) that implements the Snowflake algorithm to generate globally unique IDs over HTTP.
– It’s written in Go, packaged in a Docker container, and configured via environment variables.
File Structure
– main.go: HTTP server entry point.
– services/SnowflakeService.go: Orchestrates incoming requests and outgoing responses.
– generators/SnowflakeGenerator.go: Core snowflake algorithm implementation.
– constants/GlobalVars.go: Holds environment-variable defaults (NODE_SIZE, NODE_BITS, STEP_BITS, SERVER_PORT, SERVER_ADDRESS).
– structs/*.go: Data model for node configuration and ID format (NodeStruct, SnowflakeIdStruct).
– utils/*.go: Shared parsing and helper functions.
– Dockerfile: Containerizes the service for deployment.
README for Insights
– Exposes a GET /generate-id endpoint.
– Returns the new ID in the “X-Snowflake-Id” response header.
– Configured by .env variables.
Main Components
a. External Client (e.g., curl, upstream service)
b. (Optional) Load Balancer / API Gateway – distributes HTTP calls to multiple container instances.
c. Snowflaker Service Container
• HTTP Server (main.go)
• Service Layer (SnowflakeService)
• Generator Module (SnowflakeGenerator)
• Configuration Module (GlobalVars)
• Data Structures (NodeStruct, SnowflakeIdStruct)
• Utility Modules (GlobalFunctions, ParsingFunctions)
d. Environment Configuration (.env or orchestration secrets)
e. Docker / Container Orchestration (Kubernetes, ECS, etc.)
f. (Optional) Monitoring / Logging Sink
Relationships and Interactions
– Client → HTTP GET /generate-id → API Gateway/Load Balancer → Snowflaker HTTP Server
– HTTP Server → calls SnowflakeService.GenerateID()
– SnowflakeService → invokes SnowflakeGenerator.NextID()
– SnowflakeGenerator → reads NodeStruct & increments step counter (uses GlobalVars) → produces SnowflakeIdStruct
– SnowflakeService → sets “X-Snowflake-Id” header → returns HTTP response to client
– On startup, main.go loads configuration via GlobalVars (env), initializes NodeStruct, passes to generator.
Architectural Patterns & Principles
– Layered separation: HTTP Handler → Service Layer → Generator → Data Models → Utils
– Single Responsibility: each package/folder has one clear purpose
– Configuration via environment variables for 12-factor compliance
– Containerized microservice for easy horizontal scaling
Final Checklist
– Components: Client, Load Balancer (optional), Service Container, Config, Modules
– Labels: Endpoint name, module/function names
– Annotations: environment variables, port 8080, header “X-Snowflake-Id”