README
¶
Project structure
Project architecture follows Ben Johnson's approach from his "WTF Dial" project.
The warnly project organizes code with the following approach:
- Application domain types go in the package "warnly" —
User,Issue,Event, etc. - Implementations of the application domain go in other packages —
mysql,ch,svc, etc. - Everything is tied together in the
cmdpackages—cmd/warnly.
Application domain
The application domain is the collection of types which define what your application does without defining how it does it. For example, if you were to describe what Warnly does to a non-technical person, you would describe it in terms of Projects and Issues.
We also include interfaces for managing our application domain data types which
are used as contracts for the underlying implementations. For example, we define
a warnly.ProjectsService interface for CRUD (Create/Read/Update/Delete) actions and
MySQL does the actual implementation.
This allows all packages to share a common understanding of what each service does. We can swap out implementations, or more importantly, we can layer implementations on top of one another.
Implementation packages
Implementation packages are used as an adapter between our application domain and the
technology that we're using to implement the domain. For example,
project.ProjectService implements the warnly.ProjectService using MySQL and ClickHouse.
Implementation packages generally should not know about one another and should communicate in terms of the application domain.
These are separated out into the following packages:
server—Implements services over HTTP transport layer.ch—Implements services on ClickHouse storage layer.mysql—Implements services on MySQL storage layer.
Binary packages
The implementation packages are loosely coupled so they need to be wired
together by another package to actually make working software. That's the job
of the cmd packages which produce the final binary.
Development
You can build warnly in dev mode locally by cloning the repository, then run:
make dev
cmd/
warnly/
main.go # Entrypoint
internal/
ch/ # ClickHouse integration (OLAP methods)
chprometheus/ # Export ClickHouse metrics to Prometheus
migrator/ # SQL migration (golang-migrate wrapper)
mysql/ # MySQL integration (OLTP methods)
server/ # Handler entrypoints
session/ # User session package
stdlog/ # Slog convenience wrapper
svc/ # Service-level logic
svcotel/ # OpenTelemetry convenience wrapper
uow/ # Unit of work DB transactions abstraction
warnly/ # Root package (models, interfaces)
web/ # HTML templates rendered by templ library
Architecture Overview
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ch provides a ClickHouse connection utility.
|
Package ch provides a ClickHouse connection utility. |
|
Package chprometheus provides a Prometheus collector for ClickHouse connection pool statistics.
|
Package chprometheus provides a Prometheus collector for ClickHouse connection pool statistics. |
|
Package kafka provides a Kafka integration for Warnly.
|
Package kafka provides a Kafka integration for Warnly. |
|
Package migrator provides functionality to manage database migrations.
|
Package migrator provides functionality to manage database migrations. |
|
Package mock contains mock implementations of various interfaces.
|
Package mock contains mock implementations of various interfaces. |
|
Package mysql provides a connection to MySQL database with a connection pool.
|
Package mysql provides a connection to MySQL database with a connection pool. |
|
Package notifier implements webhook notifications.
|
Package notifier implements webhook notifications. |
|
Package server provides HTTP handlers and middlewares for application.
|
Package server provides HTTP handlers and middlewares for application. |
|
Package session provides session management functionality, including secure cookies, session storage, and session encoding/decoding using CBOR and secure cookies.
|
Package session provides session management functionality, including secure cookies, session storage, and session encoding/decoding using CBOR and secure cookies. |
|
Package stdlog provides a logger implementation using the standard library's slog package used as adapter for logging interfaces.
|
Package stdlog provides a logger implementation using the standard library's slog package used as adapter for logging interfaces. |
|
svc
|
|
|
alert
Package alert provides the implementation of the warnly.AlertService interface.
|
Package alert provides the implementation of the warnly.AlertService interface. |
|
event
Package event provides the implementation of the event service.
|
Package event provides the implementation of the event service. |
|
initializer
Package initializer initializes warnly for the first time.
|
Package initializer initializes warnly for the first time. |
|
notification
Package notification provides the implementation of the warnly.NotificationService interface.
|
Package notification provides the implementation of the warnly.NotificationService interface. |
|
project
Package project provides the implementation of the ProjectService interface, which includes methods for managing projects, issues, and teams.
|
Package project provides the implementation of the ProjectService interface, which includes methods for managing projects, issues, and teams. |
|
session
Package session provides the implementation of the SessionService interface, which includes methods for user authentication and session management.
|
Package session provides the implementation of the SessionService interface, which includes methods for user authentication and session management. |
|
system
Package system provides the implementation of the SystemService interface, which includes methods for listing slow queries, schemas, and errors.
|
Package system provides the implementation of the SystemService interface, which includes methods for listing slow queries, schemas, and errors. |
|
Package svcotel provides OpenTelemetry tracer provider interface and a no-op implementation.
|
Package svcotel provides OpenTelemetry tracer provider interface and a no-op implementation. |
|
Package uow provides an interface in which the "repositories" that participate on it are asure that the functions/actions that are called will be rollback if the Unit of Work fails at some point.
|
Package uow provides an interface in which the "repositories" that participate on it are asure that the functions/actions that are called will be rollback if the Unit of Work fails at some point. |
|
Package warnly provides the core types and interfaces for the Warnly application.
|
Package warnly provides the core types and interfaces for the Warnly application. |
|
templ: version: v0.3.1001
|
templ: version: v0.3.1001 |
|
Package worker provides background workers for processing alerts.
|
Package worker provides background workers for processing alerts. |