ginxsom/AGENTS.md

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Critical Project-Specific Rules

• Database Path: Always use db/ginxsom.db - this is hardcoded, not configurable
• SQLite Build: Uses local SQLite 3.37.2 in sqlite3-build/ directory, NOT system SQLite
• Local Development: Everything runs locally on port 9001, never use system nginx on port 80
• FastCGI Socket: Uses /tmp/ginxsom-fcgi.sock for FastCGI communication
• Config Priority: File-based config (XDG locations) overrides database config
• Admin Auth: Uses Nostr events for admin API authentication (kind 24242 with "admin" tag)
• Blob Storage: Files stored as blobs/<sha256>.<ext> where extension comes from MIME type
• Build Directory: Must create build/ directory before compilation
• Test Files: Pre-existing test files in blobs/ with specific SHA-256 names
• Server Private Key: Stored in memory only, never in database (security requirement)

Non-Standard Commands

# Restart nginx (local only)
./restart-all.sh

# Start FastCGI daemon
./scripts/start-fcgi.sh

# Test admin API with authentication
source .admin_keys && ./scripts/test_admin.sh

# Setup wizard (creates signed config events)
./scripts/setup.sh

# Local SQLite (not system)
./sqlite3-build/sqlite3 db/ginxsom.db

Critical Architecture Notes

• FastCGI app handles HEAD/PUT/DELETE requests, nginx serves GET directly from disk
• Two-tier config: File config (signed Nostr events) + database config (key-value)
• Admin API requires Nostr event signatures with specific tag structure
• Database is single source of truth for blob existence (not filesystem)
• Extension handling: URLs work with any extension, files stored with correct extension