snippet-server: Snippet Server

An internal snippet-sharing service implemented in both Go and Free Pascal, maintained in parity.

Purpose

Most services have one implementation. One implementation is enough to be wrong in ways that nobody notices. This repository has two — Go and Free Pascal — which is mildly tedious to maintain and considerably harder to deceive.

The service itself is small by design: three endpoints, one table, no authentication, nothing that edits or deletes. Smallness is not a limitation here; it is what makes the comparison meaningful. A complex service gives each implementation room to be differently wrong in ways that never surface. A minimal one does not.

Repository Structure

docs/design/                         ← canonical authority documents
  snippet-service-contract.md        ← behavioral authority (read first)
  semantic-contract.md               ← governance structure

services/go/                         ← Go implementation
services/freepascal/                 ← Free Pascal implementation
tests/                               ← shared contract tests

prompts/                             ← AI session prompt templates
meta/                                ← repository working memory

deploy/                              ← deployment configurations (scaffolded; not yet populated)
scripts/                             ← build and release scripts (scaffolded; not yet populated)
governance/                          ← governance reference material (scaffolded; not yet populated)

Starting Point

Before reading anything else, read:

docs/design/snippet-service-contract.md

This document defines what the service does. Everything else — architecture, testing, governance — is subordinate to it.

What This Service Does

Accept text snippets via HTTP POST
Store them immutably with a short ID
Return them on HTTP GET by ID
Expose a health check endpoint

It does not: authenticate users, support editing or deletion, expire content, or communicate with external services.

Implementation Philosophy

Principle	What it means here
Small binaries	No large runtime dependencies
Operational simplicity	SQLite for dev, PostgreSQL for production, no orchestration
Implementation parity	Go and Free Pascal must behave identically per the service contract
Minimal dependencies	Each implementation uses only what it needs
Reproducible deployment	Configuration via environment variables only

Governance

This repository is self-governing. Each document knows what it governs and what authority it defers to.

The governance chain:

snippet-service-contract.md  ← what the service does
semantic-contract.md         ← how documents relate
AGENTS.md                    ← how AI sessions behave
ARCHITECTURE.md              ← how the code is structured
DECISIONS.md                 ← why choices were made

See AGENTS.md for rules that apply to all AI-assisted development sessions.

Building and Running

Go

cd services/go
CGO_ENABLED=0 go build -o snippet-server .
DATABASE_FILE=./snippets.db PORT=8080 ./snippet-server

Requires Go 1.22+. Produces a static binary with no runtime dependencies.

Free Pascal

cd services/freepascal
make
DATABASE_FILE=./snippets.db PORT=8080 ./snippet-server

Requires FPC 3.2+ and libsqlite3.so.0 on the host (libsqlite3-0 on Debian/Ubuntu).

Running the contract tests

python3 tests/run.py http://localhost:8080

Requires Python 3. No external packages. See tests/README.md.

Current Status

See STATUS.md and meta/CURRENT_STATE.md.

Navigation

Document	Use it when…
`ARCHITECTURE.md`	You need to understand the structural layout
`TESTING.md`	You need to understand how correctness is verified
`COMPATIBILITY.md`	You need to verify parity between implementations
`DECISIONS.md`	You want to know why a choice was made
`ROADMAP.md`	You want to know what comes next
`AGENTS.md`	You are an AI session about to do work
`SCM.md`	You need to branch, merge, or cut a release
`meta/NEXT_STEPS.md`	You are resuming after a break and need orientation