# dishan1223/mutt architecture

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

- Interactive diagram: https://gitdiagram.com/dishan1223/mutt
- Repository: https://github.com/dishan1223/mutt

## Overview

1. **What this repo is**
   - Mutt is a Go backend for error tracking and alerting.
   - It is organized as an HTTP API service built on **Fiber**, with **PostgreSQL via GORM** for persistent data and **Redis** for fast operational concerns like rate limiting and transient state.

2. **Process entrypoint and bootstrap**
   - `cmd/main.go` is the application entrypoint.
   - Startup likely wires together environment loading, database connections, Redis, middleware, and route registration before the server begins listening.
   - The `consts/` package holds server/service configuration values used across the app.

3. **Configuration and infrastructure setup**
   - `internal/config/` contains the bootstrapping layer:
     - `loadEnv.go` loads environment variables.
     - `connectToDB.go` initializes the PostgreSQL connection.
     - `redis.go` initializes Redis.
     - `syncDatabase.go` suggests schema synchronization/migration at startup.
   - This indicates the service is designed to self-initialize its dependencies rather than rely on a separate orchestrator.

4. **Main domain boundary**
   - The core data model is centered on **users** and **projects** (`models/user.go`, `models/project.go`).
   - From the README, each project appears to be a tenant boundary for error ingestion, alerting, and API-key access.
   - Error grouping is a first-class concept, but its persistence details are abstracted behind services rather than explicit model files in this tree.

5. **Authentication boundaries**
   - There are two distinct auth paths:
     - `internal/middleware/auth.go` plus `internal/service/token.go` for user/session auth, likely JWT-based as noted in the README.
     - `internal/middleware/apiKeyAuth.go` plus `internal/service/apiKey.go` for SDK ingestion using hashed API keys.
   - This separation is important architecturally: humans/admins authenticate differently from application SDKs.

6. **Request pipeline**
   - `server/routes/main.go` defines the API surface and maps routes to handlers.
   - Middleware is applied before handlers, so requests flow through:
     - auth checks,
     - API key validation,
     - rate limiting (`internal/middleware/rateLimit.go`),
     - then into the appropriate handler.
   - This gives the system a clear boundary between cross-cutting concerns and business logic.

7. **HTTP handlers by responsibility**
   - `server/handler/AuthHandler.go` handles user authentication-related endpoints.
   - `server/handler/ProjectHandler.go` handles project lifecycle and project-level settings.
   - `server/handler/ErrorHandler.go` handles error ingestion and error-state operations.
   - `server/handler/ping.go` is a lightweight health endpoint used for liveness checks.
   - `server/handler/helper_test.go`, `auth_test.go`, and `project_test.go` show the handlers are unit-tested at the API boundary.

8. **Core business services**
   - `internal/service/` contains the domain logic:
     - `hash.go` and the README’s “fingerprint hashing” point to error grouping by normalized hash.
     - `errorGroup.go` likely manages clustering/updating grouped errors.
     - `apiKey.go` handles creation, hashing, and verification of project API keys.
     - `token.go` handles JWT creation/validation for user auth.
     - `redis.go` abstracts Redis access.
     - `hash.go` and `errorGroup.go` are especially central to the system’s main value proposition: deduplicating noisy crash streams into actionable groups.

9. **Stateful processing and storage**
   - PostgreSQL is the durable system of record for users, projects, and likely grouped errors/statuses.
   - Redis supports fast, ephemeral workflows such as rate limiting and possibly hot lookups or deduplication support.
   - `internal/config/syncDatabase.go` implies schema alignment is part of application startup, reinforcing that database state is tightly coupled to the service lifecycle.

10. **Input validation and boundary safety**
   - `internal/utils/validation.go` suggests request payload validation happens close to the API layer.
   - This is important for a system that accepts external SDK traffic, because error payloads can vary widely and need to be normalized before hashing/grouping.

11. **System behavior implied by the README**
   - The product flow is:
     - an SDK sends an error event,
     - API key middleware authenticates the project,
     - the handler passes the event to service logic,
     - the hash-based grouping logic assigns it to an existing or new group,
     - the result is persisted and may trigger alert/status changes.
   - The README’s “status tracking” and “per-project alerts” imply the project model likely controls whether notifications are emitted for that tenant.

12. **Operational and delivery notes**
   - `Makefile` likely provides local dev and build shortcuts.
   - `diagram/diagram.md` suggests the repository already documents its intended architecture visually.
   - Overall, this is a single backend service with clear separation between transport, middleware, domain services, and persistence, rather than a distributed microservice system.

Main entry points: [`server/routes/main.go`](https://github.com/dishan1223/mutt/blob/main/server/routes/main.go) (Routes), [`cmd/main.go`](https://github.com/dishan1223/mutt/blob/main/cmd/main.go) (Main), [`server/handler/ErrorHandler.go`](https://github.com/dishan1223/mutt/blob/main/server/handler/ErrorHandler.go) (Error handler), [`server/handler/AuthHandler.go`](https://github.com/dishan1223/mutt/blob/main/server/handler/AuthHandler.go) (Auth handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_bootstrap["Bootstrap"]
  node_cmd_main["Main<br/>entrypoint<br/>[main.go]"]
  node_consts_server["Server consts<br/>config<br/>[server.go]"]
  node_consts_service["Service consts<br/>config<br/>[service.go]"]
end

subgraph group_group_transport["Transport"]
  node_route_main["Routes<br/>router<br/>[main.go]"]
  node_mw_auth["Auth mw<br/>middleware<br/>[auth.go]"]
  node_mw_apikey["API key mw<br/>middleware<br/>[apiKeyAuth.go]"]
  node_mw_ratelimit["Rate limit<br/>middleware<br/>[rateLimit.go]"]
  node_h_auth["Auth handler<br/>[AuthHandler.go]"]
  node_h_project["Project handler<br/>[ProjectHandler.go]"]
  node_h_error["Error handler<br/>[ErrorHandler.go]"]
  node_h_ping["Ping<br/>handler<br/>[ping.go]"]
  node_util_validation["Validation<br/>[validation.go]"]
end

subgraph group_group_domain["Domain"]
  node_svc_token["Token svc<br/>auth service<br/>[token.go]"]
  node_svc_apikey["API key svc<br/>auth service<br/>[apiKey.go]"]
  node_svc_hash["Hash svc<br/>domain service<br/>[hash.go]"]
  node_svc_group["Group svc<br/>domain service<br/>[errorGroup.go]"]
  node_svc_redis["Redis svc<br/>cache service<br/>[redis.go]"]
  node_model_user["User<br/>model<br/>[user.go]"]
  node_model_project["Project<br/>model<br/>[project.go]"]
end

subgraph group_group_infra["Infrastructure"]
  node_config_loadenv["Load env<br/>bootstrap<br/>[loadEnv.go]"]
  node_config_db[("DB connect<br/>bootstrap<br/>[connectToDB.go]")]
  node_config_redis[("Redis setup<br/>bootstrap<br/>[redis.go]")]
  node_config_syncdb["Sync DB<br/>bootstrap<br/>[syncDatabase.go]"]
end

node_cmd_main -->|"loads"| node_config_loadenv
node_cmd_main -->|"connects"| node_config_db
node_cmd_main -->|"connects"| node_config_redis
node_cmd_main -->|"syncs"| node_config_syncdb
node_cmd_main -->|"starts"| node_route_main
node_cmd_main -->|"uses"| node_consts_server
node_cmd_main -->|"uses"| node_consts_service
node_route_main -->|"applies"| node_mw_auth
node_route_main -->|"applies"| node_mw_apikey
node_route_main -->|"applies"| node_mw_ratelimit
node_route_main -->|"maps"| node_h_auth
node_route_main -->|"maps"| node_h_project
node_route_main -->|"maps"| node_h_error
node_route_main -->|"maps"| node_h_ping
node_h_auth -->|"uses"| node_svc_token
node_h_auth -->|"reads/writes"| node_model_user
node_h_project -->|"reads/writes"| node_model_project
node_h_error -->|"authenticates"| node_svc_apikey
node_h_error -->|"groups"| node_svc_hash
node_h_error -->|"assigns"| node_svc_group
node_h_error -->|"uses"| node_svc_redis
node_svc_apikey -->|"binds to"| node_model_project
node_svc_token -->|"binds to"| node_model_user
node_svc_group -->|"scoped by"| node_model_project
node_svc_redis -->|"backed by"| node_config_redis
node_util_validation -->|"guards"| node_h_error
node_util_validation -->|"guards"| node_h_auth
node_util_validation -->|"guards"| node_h_project

click node_cmd_main "https://github.com/dishan1223/mutt/blob/main/cmd/main.go"
click node_consts_server "https://github.com/dishan1223/mutt/blob/main/consts/server.go"
click node_consts_service "https://github.com/dishan1223/mutt/blob/main/consts/service.go"
click node_config_loadenv "https://github.com/dishan1223/mutt/blob/main/internal/config/loadEnv.go"
click node_config_db "https://github.com/dishan1223/mutt/blob/main/internal/config/connectToDB.go"
click node_config_redis "https://github.com/dishan1223/mutt/blob/main/internal/config/redis.go"
click node_config_syncdb "https://github.com/dishan1223/mutt/blob/main/internal/config/syncDatabase.go"
click node_route_main "https://github.com/dishan1223/mutt/blob/main/server/routes/main.go"
click node_mw_auth "https://github.com/dishan1223/mutt/blob/main/internal/middleware/auth.go"
click node_mw_apikey "https://github.com/dishan1223/mutt/blob/main/internal/middleware/apiKeyAuth.go"
click node_mw_ratelimit "https://github.com/dishan1223/mutt/blob/main/internal/middleware/rateLimit.go"
click node_h_auth "https://github.com/dishan1223/mutt/blob/main/server/handler/AuthHandler.go"
click node_h_project "https://github.com/dishan1223/mutt/blob/main/server/handler/ProjectHandler.go"
click node_h_error "https://github.com/dishan1223/mutt/blob/main/server/handler/ErrorHandler.go"
click node_h_ping "https://github.com/dishan1223/mutt/blob/main/server/handler/ping.go"
click node_svc_token "https://github.com/dishan1223/mutt/blob/main/internal/service/token.go"
click node_svc_apikey "https://github.com/dishan1223/mutt/blob/main/internal/service/apiKey.go"
click node_svc_hash "https://github.com/dishan1223/mutt/blob/main/internal/service/hash.go"
click node_svc_group "https://github.com/dishan1223/mutt/blob/main/internal/service/errorGroup.go"
click node_svc_redis "https://github.com/dishan1223/mutt/blob/main/internal/service/redis.go"
click node_model_user "https://github.com/dishan1223/mutt/blob/main/models/user.go"
click node_model_project "https://github.com/dishan1223/mutt/blob/main/models/project.go"
click node_util_validation "https://github.com/dishan1223/mutt/blob/main/internal/utils/validation.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_consts_server,node_consts_service toneBlue
class node_route_main,node_mw_auth,node_mw_apikey,node_mw_ratelimit,node_h_auth,node_h_project,node_h_error,node_h_ping,node_util_validation toneAmber
class node_svc_token,node_svc_apikey,node_svc_hash,node_svc_group,node_svc_redis,node_model_user,node_model_project toneMint
class node_config_loadenv,node_config_db,node_config_redis,node_config_syncdb toneRose
```

## Components

### Bootstrap

Process startup and dependency wiring

- [Main](https://github.com/dishan1223/mutt/blob/main/cmd/main.go): entrypoint · Application entrypoint and server bootstrap · `cmd/main.go`
- [Server consts](https://github.com/dishan1223/mutt/blob/main/consts/server.go): config · Shared server settings · `consts/server.go`
- [Service consts](https://github.com/dishan1223/mutt/blob/main/consts/service.go): config · Shared service settings · `consts/service.go`

### Transport

HTTP routing, middleware, and handlers

- [Routes](https://github.com/dishan1223/mutt/blob/main/server/routes/main.go): router · HTTP route registration and wiring · `server/routes/main.go`
- [Auth mw](https://github.com/dishan1223/mutt/blob/main/internal/middleware/auth.go): middleware · User/session authentication checks · `internal/middleware/auth.go`
- [API key mw](https://github.com/dishan1223/mutt/blob/main/internal/middleware/apiKeyAuth.go): middleware · SDK ingestion authentication · `internal/middleware/apiKeyAuth.go`
- [Rate limit](https://github.com/dishan1223/mutt/blob/main/internal/middleware/rateLimit.go): middleware · Request throttling and abuse control · `internal/middleware/rateLimit.go`
- [Auth handler](https://github.com/dishan1223/mutt/blob/main/server/handler/AuthHandler.go): handler · Authentication endpoints · `server/handler/AuthHandler.go`
- [Project handler](https://github.com/dishan1223/mutt/blob/main/server/handler/ProjectHandler.go): handler · Project management endpoints · `server/handler/ProjectHandler.go`
- [Error handler](https://github.com/dishan1223/mutt/blob/main/server/handler/ErrorHandler.go): handler · Error ingestion and error-state endpoints · `server/handler/ErrorHandler.go`
- [Ping](https://github.com/dishan1223/mutt/blob/main/server/handler/ping.go): handler · Health check endpoint · `server/handler/ping.go`
- [Validation](https://github.com/dishan1223/mutt/blob/main/internal/utils/validation.go): utility · Request payload validation · `internal/utils/validation.go`

### Domain

Core business logic and models

- [Token svc](https://github.com/dishan1223/mutt/blob/main/internal/service/token.go): auth service · JWT creation and validation · `internal/service/token.go`
- [API key svc](https://github.com/dishan1223/mutt/blob/main/internal/service/apiKey.go): auth service · API key creation and verification · `internal/service/apiKey.go`
- [Hash svc](https://github.com/dishan1223/mutt/blob/main/internal/service/hash.go): domain service · Fingerprint hashing for grouping · `internal/service/hash.go`
- [Group svc](https://github.com/dishan1223/mutt/blob/main/internal/service/errorGroup.go): domain service · Error grouping and cluster management · `internal/service/errorGroup.go`
- [Redis svc](https://github.com/dishan1223/mutt/blob/main/internal/service/redis.go): cache service · Redis access abstraction · `internal/service/redis.go`
- [User](https://github.com/dishan1223/mutt/blob/main/models/user.go): model · User account and auth state · `models/user.go`
- [Project](https://github.com/dishan1223/mutt/blob/main/models/project.go): model · Tenant boundary for error ingestion and alerts · `models/project.go`

### Infrastructure

Database, Redis, and environment setup

- [Load env](https://github.com/dishan1223/mutt/blob/main/internal/config/loadEnv.go): bootstrap · Environment variable loading · `internal/config/loadEnv.go`
- [DB connect](https://github.com/dishan1223/mutt/blob/main/internal/config/connectToDB.go): bootstrap · PostgreSQL connection setup · `internal/config/connectToDB.go`
- [Redis setup](https://github.com/dishan1223/mutt/blob/main/internal/config/redis.go): bootstrap · Redis connection setup · `internal/config/redis.go`
- [Sync DB](https://github.com/dishan1223/mutt/blob/main/internal/config/syncDatabase.go): bootstrap · Database schema alignment at startup · `internal/config/syncDatabase.go`

## Connections

- Main → Load env: loads · Bootstraps environment configuration
- Main → DB connect: connects · Initializes PostgreSQL
- Main → Redis setup: connects · Initializes Redis
- Main → Sync DB: syncs · Aligns database schema during startup
- Main → Routes: starts · Registers HTTP routes and starts the server
- Main → Server consts: uses · Reads server configuration
- Main → Service consts: uses · Reads service configuration
- Routes → Auth mw: applies · Protects user-facing routes
- Routes → API key mw: applies · Protects SDK ingestion routes
- Routes → Rate limit: applies · Throttles incoming traffic
- Routes → Auth handler: maps · Exposes auth endpoints
- Routes → Project handler: maps · Exposes project endpoints
- Routes → Error handler: maps · Exposes error endpoints
- Routes → Ping: maps · Exposes health endpoint
- Auth handler → Token svc: uses · Issues and verifies user tokens
- Auth handler → User: reads/writes · Operates on user accounts
- Project handler → Project: reads/writes · Manages project records
- Error handler → API key svc: authenticates · Validates project API keys
- Error handler → Hash svc: groups · Computes error fingerprints
- Error handler → Group svc: assigns · Creates or updates error groups
- Error handler → Redis svc: uses · Touches fast operational state
- API key svc → Project: binds to · Scopes API keys to projects
- Token svc → User: binds to · Scopes tokens to users
- Group svc → Project: scoped by · Groups errors within a project tenant
- Redis svc → Redis setup: backed by · Uses Redis connection from bootstrap
- Validation → Error handler: guards · Validates inbound error payloads
- Validation → Auth handler: guards · Validates auth payloads
- Validation → Project handler: guards · Validates project payloads