# hashednode/snowflaker architecture

> Architecture diagram of the GitHub repository hashednode/snowflaker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashednode/snowflaker
- Repository: https://github.com/hashednode/snowflaker

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::external
    LoadBalancer["Load Balancer / API Gateway"]:::external

    %% Docker Orchestration
    Orchestration["Container Orchestration"]:::external

    %% Snowflaker Service Container
    subgraph "Snowflaker Service Container" 
        direction TB
        HTTPServer["HTTP Server\n(main.go)"]:::runtime
        SnowflakeService["SnowflakeService\n(services/SnowflakeService.go)"]:::module
        SnowflakeGenerator["SnowflakeGenerator\n(generators/SnowflakeGenerator.go)"]:::module
        GlobalVars["Config Module\n(constants/GlobalVars.go)"]:::config
        NodeStruct["NodeStruct\n(structs/NodeStruct.go)"]:::data
        SnowflakeIdStruct["SnowflakeIdStruct\n(structs/SnowflakeIdStruct.go)"]:::data
        GlobalFunctions["GlobalFunctions\n(utils/GlobalFunctions.go)"]:::module
        ParsingFunctions["ParsingFunctions\n(utils/ParsingFunctions.go)"]:::module
    end

    %% Config .env
    Env["Environment Variables\n(.env)"]:::config

    %% Monitoring/Logging
    Monitoring["Monitoring / Logging"]:::external

    %% Request Flow
    Client -->|"HTTP GET /generate-id"| LoadBalancer
    LoadBalancer -->|"/generate-id"| HTTPServer
    HTTPServer -->|"GenerateID()"| SnowflakeService
    SnowflakeService -->|"NextID()"| SnowflakeGenerator
    SnowflakeGenerator -->|uses| NodeStruct
    SnowflakeGenerator -->|reads| GlobalVars
    SnowflakeGenerator -->|invokes| GlobalFunctions
    SnowflakeGenerator -->|invokes| ParsingFunctions
    SnowflakeGenerator -->|returns SnowflakeIdStruct| SnowflakeService
    SnowflakeService -->|sets X-Snowflake-Id header| HTTPServer
    HTTPServer -->|HTTP Response| Client

    %% Startup Flow
    HTTPServer -->|loads config| GlobalVars
    GlobalVars -->|reads| Env

    %% Orchestration and Monitoring
    Orchestration -->|deploys| HTTPServer
    HTTPServer -->|emits logs/metrics| Monitoring

    %% Click Events
    click HTTPServer "https://github.com/hashednode/snowflaker/blob/main/main.go"
    click SnowflakeService "https://github.com/hashednode/snowflaker/blob/main/services/SnowflakeService.go"
    click SnowflakeGenerator "https://github.com/hashednode/snowflaker/blob/main/generators/SnowflakeGenerator.go"
    click GlobalVars "https://github.com/hashednode/snowflaker/blob/main/constants/GlobalVars.go"
    click NodeStruct "https://github.com/hashednode/snowflaker/blob/main/structs/NodeStruct.go"
    click SnowflakeIdStruct "https://github.com/hashednode/snowflaker/blob/main/structs/SnowflakeIdStruct.go"
    click GlobalFunctions "https://github.com/hashednode/snowflaker/blob/main/utils/GlobalFunctions.go"
    click ParsingFunctions "https://github.com/hashednode/snowflaker/blob/main/utils/ParsingFunctions.go"
    click Orchestration "https://github.com/hashednode/snowflaker/tree/main/Dockerfile"
    click Client "https://github.com/hashednode/snowflaker/blob/main/README.md"

    %% Styles
    classDef external fill:#BBDEFB,stroke:#2196F3,color:#0D47A1,stroke-width:1px
    classDef runtime fill:#C8E6C9,stroke:#388E3C,color:#1B5E20,stroke-width:1px
    classDef module fill:#FFE0B2,stroke:#F57C00,color:#E65100,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#9E9E9E,color:#424242,stroke-width:1px
    classDef data fill:#F5F5F5,stroke:#BDBDBD,color:#212121,stroke-width:1px
```
