Demeterics Codebase Reference

This document provides context for automated code analysis and feedback processing.

Project Overview

Demeterics is an enterprise-grade platform for tracking, analyzing, and evaluating Large Language Model (LLM) interactions at scale.

Technology Stack:

• Backend: Go 1.22 on Google App Engine Standard
• Frontend: Bootstrap 5 + HTMX (server-side rendering)
• Storage: BigQuery (analytics), Datastore (metadata), Memcache v2 (caching)
• Authentication: Google OAuth2 for UI, API keys for programmatic access
• Async Processing: Cloud Tasks for background BigQuery writes

Directory Structure

portal/app/
├── cmd/server/          # Main application entry point
├── internal/
│   ├── api/             # JSON API handlers (REST endpoints)
│   ├── web/             # HTML handlers (templates, HTMX)
│   │   ├── auth/        # Authenticated page handlers
│   │   └── public/      # Public page handlers
│   ├── config/          # Configuration loading
│   ├── data/            # Data layer (Datastore, caching)
│   └── tools/           # LLM tools for code exploration
├── templates/           # HTML templates (Go html/template)
├── static/
│   ├── js/              # JavaScript files
│   ├── css/             # CSS stylesheets
│   └── img/             # Images and assets
└── vendor-private/api/  # Vendored shared code from ../api

Key Patterns

Web vs API Separation

• Web handlers (internal/web/): Return HTML via templates or HTMX fragments
• API handlers (internal/api/): Return JSON only, for JavaScript/SDK consumption

Template Data

All web handlers use data structs that include BaseData:

type PageData struct {
    BaseData              // Includes Session, CreditBalance, BasicMode, etc.
    CustomField string    // Page-specific fields
}

HTMX Integration

• Most forms use HTMX for dynamic updates
• Partial HTML fragments returned for in-page updates
• Full page refreshes use standard template rendering

BigQuery Tables

• interactions: LLM call tracking (partitioned by question_time)
• touchpoints: User session tracking
• eval_runs, eval_results: Evaluation tracking

Common Bug Categories

1. Template Errors: Missing fields in data structs cause runtime panics
2. HTMX Issues: JavaScript conflicts, missing hx-* attributes
3. Session Issues: Cookie domain problems, OAuth flow errors
4. BigQuery Schema: Field type mismatches cause insert failures
5. Credit System: Balance calculation, Stripe webhook handling

File Naming Conventions

• Handlers: {feature}.go (e.g., dashboard.go, credits.go)
• Templates: {feature}.html, {feature}_partial.html
• Static: {feature}.{hash}.js for versioned assets

Common Fixes

Adding a new page

1. Create handler in internal/web/auth/ or internal/web/public/
2. Create template in templates/
3. Register route in cmd/server/main.go
4. Add to navigation in base.html or relevant partial

Fixing template errors

1. Check struct has all fields referenced in template
2. Verify BaseData is properly embedded
3. Ensure BasicMode, Session fields are set correctly

API endpoint issues

1. Check authentication middleware is applied
2. Verify JSON response format
3. Check CORS headers if called from JavaScript