TRACES

Your Year in Review — Timeline, Memories & Analytics

---

Features

📅 Timeline — Alternating event cards with rich media, markdown descriptions, and weather data. 📊 Activity Graph — GitHub-style contribution heatmap showing event density throughout the year. 🖼️ Media Gallery — Image, video, and audio player with modal viewing and infinite scroll. 🗺️ Map View — Interactive Leaflet map with geo-tagged events, colored markers by media type.

👥 Persons — Track people with avatars, color coding, bios, and linked events. 📈 Year Comparison — Side-by-side stats comparing any two years. 🔔 Gotify Notifications — Real-time alerts for new events, uploads, and activity. 🌙 Dark Mode — Automatic theme following system preference, with manual toggle.

Tech Stack

Layer	Technology
Backend	Go 1.26 with Gin framework
Database	SQLite3 via mattn/go-sqlite3
Frontend	TypeScript 6.0, compiled to vanilla JS
UI	Bootstrap 5, Font Awesome 7
Maps	Leaflet.js with OpenStreetMap
Auth	bcrypt password hashing, CSRF tokens
CI/CD	GitHub Actions, Playwright E2E tests

Quick Start

Docker (Recommended)

docker build -t traces .
docker run -d -p 6270:6270 -v traces-data:/db traces

Open http://localhost:6270 in your browser.

Manual Setup

# Install dependencies
go mod download
npm install

# Build TypeScript frontend
npm run build:ts

# Build the server
go build -o traces-server .

# Run
./traces-server

Development

# Install dev tools (requires `air` for hot reload)
task dev

# Run Go unit tests
go test -v ./...

# Run E2E tests (starts server automatically)
task test-e2e

# Run all pre-push checks
task prepush

See AGENTS.md for the full development guide and available tasks.

First-Time Setup

1. Navigate to http://localhost:6270
2. You'll be redirected to /setup.html
3. Create your admin username and password
4. Login at /login.html to access the admin panel

Environment Variables

Variable	Description	Default
PORT	HTTP port	6270
DOCKER	Run in Docker mode	false
PUBLIC_MODE	Allow unauthenticated access to public events	false
GOTIFY_URL	Gotify server URL for notifications	—
GOTIFY_TOKEN	Gotify app token	—
GOTIFY_ENABLED	Enable Gotify notifications	false
TRACES_JPEG_QUALITY	JPEG quality (1–100) for full-size image uploads	82
TRACES_NOMINATIM_URL	Nominatim reverse-geocoding endpoint (blank to disable suggestions)	https://nominatim.openstreetmap.org/reverse
OIDC_ENABLED	Enable OIDC login via Authelia (true/false); password login stays as fallback	false
OIDC_ISSUER_URL	OIDC issuer, e.g. https://authelia.vandijke.xyz	—
OIDC_CLIENT_ID	OIDC client id registered in Authelia	—
OIDC_CLIENT_SECRET_FILE	Path to file containing the client secret (preferred; never commit)	—
OIDC_CLIENT_SECRET	Client secret inline (dev only; prefer _FILE)	—
OIDC_REDIRECT_URL	Callback URL, e.g. https://traces.vandijke.xyz/api/auth/oidc/callback	—
OIDC_SCOPES	Space-separated scopes	openid email profile groups

Optional runtime dependency — ffmpeg: When ffmpeg is on the server PATH, TRACES generates a poster-frame thumbnail for every uploaded video (used in timeline/grid/lightbox previews). Without it, uploads still work and videos fall back to the generic video placeholder.

Observability (OpenTelemetry)

TRACES exports traces, metrics, and logs over OTLP and always attaches a Prometheus reader at /metrics. The following environment variables are read:

Variable	Effect
OTEL_EXPORTER_OTLP_ENDPOINT	Collector endpoint; also implies all signals are enabled unless individually set to none
OTEL_TRACES_EXPORTER	Set to none to disable traces only
OTEL_METRICS_EXPORTER	Set to none to disable metrics only
OTEL_LOGS_EXPORTER	Set to none to disable logs only
OTEL_EXPORTER_OTLP_PROTOCOL	grpc (default) or http/protobuf
OTEL_SERVICE_NAME	Service name
OTEL_RESOURCE_ATTRIBUTES	Comma-separated resource attributes
OTEL_TRACES_SAMPLER	always_on, always_off, traceidratio, parentbased_*
OTEL_TRACES_SAMPLER_ARG	Ratio for the *traceidratio samplers

When OTEL_EXPORTER_OTLP_ENDPOINT is empty, each enabled signal writes to its stdout exporter instead. If an OTLP exporter cannot be constructed, that signal falls back to stdout rather than aborting initialization. Environment variables take precedence over the DB-backed /api/otel/config settings.

Not read (unsupported): per-signal endpoints (OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT), OTLP headers, timeouts, compression, and TLS settings. Only the shared endpoint above is honored.

Project Structure

traces/
├── main.go                # Go backend (Gin framework)
├── *_test.go              # Go unit tests (split by domain: auth, events, uploads, search, stats, ...)
├── go.mod / go.sum        # Go module dependencies
├── ts/                    # TypeScript source files
│   ├── index.ts           # Timeline page
│   ├── admin.ts           # Admin panel
│   ├── login.ts           # Login page
│   ├── setup.ts           # Setup page
│   ├── map.ts             # Map page
│   └── shared/            # Shared frontend modules (format, api, analytics, map, types)
├── static/                # Static assets served by the app
│   ├── index.html         # Main timeline page
│   ├── admin.html         # Admin management panel
│   ├── map.html           # Standalone map page
│   ├── login.html         # Admin login
│   ├── setup.html         # First-time setup
│   ├── style.css          # Shared styles
│   ├── js/                # Compiled JavaScript (gitignored)
│   │   ├── index.js       # Compiled from ts/index.ts
│   │   ├── admin.js       # Compiled from ts/admin.ts
│   │   └── ...
│   └── images/            # Static images
├── tests/                 # Playwright E2E tests
│   ├── index.spec.ts
│   ├── admin.spec.ts
│   └── features.spec.ts
├── playwright.config.ts   # Playwright configuration
├── tsconfig.json          # TypeScript configuration
├── Taskfile.yml           # Task runner
├── Dockerfile             # Docker build
└── media/                 # Uploaded media files

API Endpoints

Method	Endpoint	Auth	Description
GET	/api/events	No	List events (filter by year/month)
GET	/api/events/full	No	All events with person data
GET	/api/events/search	No	Search events
POST	/api/events	Yes	Create/update event
DELETE	/api/events	Yes	Delete event
POST	/api/upload	Yes	Upload media file
GET	/api/stats	No	Event statistics
GET	/api/contributions	No	Activity heatmap data
GET	/api/map	No	GeoJSON for map
GET	/api/persons	No	List persons
POST	/api/persons	Yes	Create/update person
DELETE	/api/persons	Yes	Delete person
GET/POST	/api/gotify/config	Yes	Gotify settings
POST	/api/gotify/test	Yes	Test notification
POST	/api/login	No	Admin login
POST	/api/logout	No	Admin logout

OpenAPI: GET /api-docs returns the single committed OpenAPI document (docs/swagger.json).

Breaking (docs endpoints): the Swagger UI (/swagger/*any) and the /docs redirect have been removed, and /api-docs now returns the current generated specification instead of the previous stale copy.

Philosophy

TRACES is designed to be:

• Self-contained — No external dependencies beyond Go and SQLite
• Simple — Minimal configuration, batteries included
• Personal — Track your life, not just application metrics
• Beautiful — Clean timeline, gallery, and map views

License

MIT