How dishan1223/mutt works
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: routes/main.go Routes · cmd/main.go Main · ErrorHandler.go Error handler · AuthHandler.go Auth handler
Components 23
Bootstrap
Process startup and dependency wiring
- Main · Application entrypoint and server bootstrap
cmd/main.go - Server consts · Shared server settings
consts/server.go - Service consts · Shared service settings
consts/service.go
Transport
HTTP routing, middleware, and handlers
- Routes · HTTP route registration and wiring
server/routes/main.go - Auth mw · User/session authentication checks
internal/middleware/auth.go - API key mw · SDK ingestion authentication
internal/middleware/apiKeyAuth.go - Rate limit · Request throttling and abuse control
internal/middleware/rateLimit.go - Auth handler · Authentication endpoints
server/handler/AuthHandler.go - Project handler · Project management endpoints
server/handler/ProjectHandler.go - Error handler · Error ingestion and error-state endpoints
server/handler/ErrorHandler.go - Ping · Health check endpoint
server/handler/ping.go - Validation · Request payload validation
internal/utils/validation.go
Domain
Core business logic and models
- Token svc · JWT creation and validation
internal/service/token.go - API key svc · API key creation and verification
internal/service/apiKey.go - Hash svc · Fingerprint hashing for grouping
internal/service/hash.go - Group svc · Error grouping and cluster management
internal/service/errorGroup.go - Redis svc · Redis access abstraction
internal/service/redis.go - User · User account and auth state
models/user.go - Project · Tenant boundary for error ingestion and alerts
models/project.go
Infrastructure
Database, Redis, and environment setup
- Load env · Environment variable loading
internal/config/loadEnv.go - DB connect · PostgreSQL connection setup
internal/config/connectToDB.go - Redis setup · Redis connection setup
internal/config/redis.go - Sync DB · Database schema alignment at startup
internal/config/syncDatabase.go
Connections 28
- 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