README
¶
GoKnut
A self-hosted Twitch Chat Archiver & Explorer — archive chat messages in real-time and explore them through a web interface.
Features
- Live Chat Streaming — Real-time chat view with <1s latency via Server-Sent Events
- Full-Text Search — Search messages and users with filters (channel, user, time range) using SQLite FTS5
- Channel Management — Add, enable/disable, and manage tracked Twitch channels
- User Activity Tracking — View user profiles with message history and activity stats
- Server-Rendered UI — Fast, lightweight interface built with HTMX and Tailwind CSS
Quick Start
Prerequisites: Go 1.22+
# Build
make build
# Run (anonymous mode - no credentials required)
export TWITCH_AUTH_MODE=anonymous
./bin/goknut --db-path=./twitch.db --http-addr=:8080
Open http://localhost:8080 in your browser.
Documentation
See docs/README.md for detailed documentation including:
- Configuration options (environment variables and flags)
- Architecture overview
- Performance targets
- Running with authentication
- Docker deployment with observability stack
Development
make build # Build binary to bin/goknut
make run # Build and run
make test # Run all tests
make clean # Clean build artifacts
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
server
command
Package main provides the entry point for the GoKnut Twitch Chat Archiver.
|
Package main provides the entry point for the GoKnut Twitch Chat Archiver. |
|
internal
|
|
|
config
Package config provides configuration loading and validation for the Twitch Chat Archiver.
|
Package config provides configuration loading and validation for the Twitch Chat Archiver. |
|
http
Package http provides the HTTP server and handlers for the web UI.
|
Package http provides the HTTP server and handlers for the web UI. |
|
http/dto
Package dto provides shared data transfer objects and validation helpers.
|
Package dto provides shared data transfer objects and validation helpers. |
|
http/handlers
Package handlers provides HTTP handlers for the web UI.
|
Package handlers provides HTTP handlers for the web UI. |
|
ingestion
Package ingestion provides message ingestion pipeline with batching.
|
Package ingestion provides message ingestion pipeline with batching. |
|
irc
Package irc provides a Twitch IRC client for chat message ingestion.
|
Package irc provides a Twitch IRC client for chat message ingestion. |
|
observability
Package observability provides structured logging and metrics for the application.
|
Package observability provides structured logging and metrics for the application. |
|
repository
Package repository provides database access for the Twitch Chat Archiver.
|
Package repository provides database access for the Twitch Chat Archiver. |
|
search
Package search provides search functionality for users and messages.
|
Package search provides search functionality for users and messages. |
|
services
Package services provides business logic for the Twitch Chat Archiver.
|
Package services provides business logic for the Twitch Chat Archiver. |
|
tests
|
|
|
integration/fakes
Package fakes provides test fakes for integration testing.
|
Package fakes provides test fakes for integration testing. |
Click to show internal directories.
Click to hide internal directories.