admin

Admin Package

Purpose & Responsibilities

The admin package provides a web-based administration interface for the LLM Proxy. It handles:

• Web UI Server: Separate HTTP server with Gin framework for admin interface
• Session Management: Cookie-based sessions with configurable expiration
• Management API Client: HTTP client for communicating with the Management API
• Dashboard: Overview of projects, tokens, and system statistics
• Project Management: CRUD operations for projects via web interface
• Token Management: Create, list, view, and revoke tokens
• Audit Log Viewer: Browse and search security audit events
• Template Rendering: Server-side HTML templates with helper functions

Architecture

graph TB
    subgraph Browser
        UI[Web Browser]
    end
    
    subgraph AdminServer["Admin Server (port 8081)"]
        GIN[Gin Engine]
        SESS[Session Manager]
        TPL[Template Engine]
        AC[API Client]
    end
    
    subgraph ManagementAPI["Management API (port 8080)"]
        API[REST API Handlers]
        DB[(Database)]
    end
    
    UI -->|HTTP| GIN
    GIN --> SESS
    GIN --> TPL
    GIN --> AC
    AC -->|HTTP + Bearer Token| API
    API --> DB

Two-Server Architecture

The admin package runs as a separate HTTP server from the main proxy:

This separation provides:

• Independent deployment and scaling
• Different security models (cookies vs. bearer tokens)
• Isolated failure domains

Key Types & Interfaces

Constructor Functions

Session Management

The admin UI uses cookie-based sessions for user authentication:

sequenceDiagram
    participant Browser
    participant AdminUI
    participant ManagementAPI
    
    Browser->>AdminUI: POST /admin/login (token)
    AdminUI->>ManagementAPI: Validate token
    ManagementAPI-->>AdminUI: Valid
    AdminUI->>AdminUI: Create session
    AdminUI-->>Browser: Set cookie
    
    Browser->>AdminUI: GET /admin/projects (with cookie)
    AdminUI->>AdminUI: Validate session
    AdminUI->>ManagementAPI: GET /manage/projects
    ManagementAPI-->>AdminUI: Project list
    AdminUI-->>Browser: Rendered HTML

Session Features

API Client Usage

The APIClient wraps HTTP calls to the Management API:

Example: Creating a Token

client := admin.NewAPIClient("http://localhost:8080", managementToken)

// Create token with 60-minute expiration and no request limit
response, err := client.CreateToken(ctx, projectID, 60, nil)
if err != nil {
    // Handle error
}

fmt.Println("New token:", response.Token)
fmt.Println("Expires at:", response.ExpiresAt)

Example: Listing Projects

projects, pagination, err := client.GetProjects(ctx, page, pageSize)
if err != nil {
    // Handle error
}

for _, project := range projects {
    fmt.Printf("Project: %s (%s)\n", project.Name, project.ID)
}

Context Propagation

The API client forwards browser metadata to the Management API for audit logging:

Web UI Routes

Authentication

Dashboard & Projects

Tokens

Audit Logs

Static Assets

Configuration

Environment Variables

AdminUIConfig Options

Template System

The admin UI uses Go's html/template package with custom helper functions:

Template Structure

web/templates/
├── layouts/
│   └── base.html         # Base layout with header/footer
├── dashboard/
│   └── index.html        # Dashboard page
├── projects/
│   ├── list.html         # Project list
│   ├── show.html         # Project details
│   └── form.html         # Create/edit form
├── tokens/
│   ├── list.html         # Token list
│   ├── show.html         # Token details
│   └── form.html         # Create token form
└── audit/
    ├── list.html         # Audit log list
    └── show.html         # Event details

Custom Template Functions

See server.go for the full list of available template functions.

Usage Examples

Starting the Admin Server

package main

import (
    "github.com/sofatutor/llm-proxy/internal/admin"
    "github.com/sofatutor/llm-proxy/internal/config"
)

func main() {
    cfg, err := config.New()
    if err != nil {
        panic(err)
    }

    server, err := admin.NewServer(cfg)
    if err != nil {
        panic(err)
    }

    if err := server.Start(); err != nil {
        panic(err)
    }
}

Custom API Client Usage

// Create client
client := admin.NewAPIClient(
    "http://localhost:8080",
    "your-management-token",
)

// Get dashboard data
ctx := context.Background()
dashboard, err := client.GetDashboardData(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Projects: %d\n", dashboard.TotalProjects)
fmt.Printf("Tokens: %d\n", dashboard.TotalTokens)

Token Obfuscation

// Obfuscate token for display
token := "sk-AYB2gH5xQZ1234567890ab"
obfuscated := admin.ObfuscateToken(token)
// Output: "sk-AYB2g...90ab"

// Obfuscate API key
apiKey := "sk-proj-1234567890abcdefghijklmnopqrstuvwxyz"
obfuscated := admin.ObfuscateAPIKey(apiKey)
// Output: "sk-proj-...wxyz"

Note: HTML templates use the obfuscateToken and obfuscateAPIKey template helpers. The token helper is UI-oriented and may use a different obfuscation strategy than admin.ObfuscateToken.

Troubleshooting

Common Issues

Debug Headers

Response headers for debugging:

Related Packages

Files

Testing Strategy

Goals

• Achieve and maintain 90%+ code coverage for all admin server logic.
• Cover all HTTP handlers, error branches, and template rendering code paths.
• Ensure tests are robust to changes in working directory and template locations.

Test Data

• Minimal HTML templates for all routes are in internal/admin/testdata/.
• Tests use a helper (testTemplateDir()) to resolve the correct path for templates, making tests CWD-agnostic.

Adding/Updating Tests

• For each new handler or feature, add a corresponding test in server_test.go.
• If a handler renders a new template, add a minimal HTML file to testdata/.
• Use table-driven tests for logic with multiple input/output cases.
• Use mock API clients to isolate handler logic from external dependencies.

Running Tests

• Run all tests and check coverage with:

  make test-coverage
  # or
  go test -cover ./internal/admin/...
  

Coverage Enforcement

• PRs are not merged unless coverage is 90%+.
• Coverage is checked in CI and locally.

Special Conventions

• Template path resolution is handled by a helper to ensure tests work regardless of CWD.
• Minimal templates are used to satisfy the loader and cover template parsing code paths.

Troubleshooting

• If tests fail due to missing templates, ensure all required files exist in testdata/.
• If coverage drops, check for untested error branches or new code.