From 8ff4a200a67b7fe15c98cb55dfd734df6c009ae4 Mon Sep 17 00:00:00 2001
From: Dan Notestein <dan@syncad.com>
Date: Tue, 30 Dec 2025 00:55:56 -0500
Subject: [PATCH] Add CLAUDE.md for AI-assisted development

---
 CLAUDE.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2294d29
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+NFT Tracker is a PostgreSQL-based application for tracking NFTs on the Hive blockchain, built on HAF (Hive Application Framework). It provides a REST API via PostgREST with Nginx URL rewriting.
+
+## Common Commands
+
+### Testing
+```bash
+./regress.sh                    # Run all regression tests
+./regress.sh -v                 # Verbose output
+./regress.sh -k                 # Keep test database after tests
+./regress.sh -v -k test_name    # Run specific test with verbose output
+```
+
+### Database Installation
+```bash
+./scripts/install_app.sh                              # Install schema
+./scripts/install_app.sh --postgres-url=postgresql://...
+./scripts/uninstall_app.sh                            # Remove app
+```
+
+### Block Processing
+```bash
+./scripts/process_blocks.sh                  # Process Hive blocks
+./scripts/process_blocks.sh --stop-at-block=N
+```
+
+### OpenAPI/Nginx Config Generation
+```bash
+./scripts/openapi_rewrite.sh    # Regenerate OpenAPI specs and nginx rewrite rules
+```
+
+### Docker
+```bash
+docker buildx bake full         # Build locally
+```
+
+## Architecture
+
+### Three Main Components
+
+1. **Database Layer** (`/db/`)
+   - `schema.sql` - Core tables: `types`, `instances`, `authorized_issuers`
+   - `nft_actions.sql` - NFT operations (register, modify, issue, soulbind, set_data, transfer)
+   - `main_loop.sql` - Block processing pipeline calling `nfttracker_app.main()`
+
+2. **API Endpoints** (`/endpoints/`)
+   - `endpoint_schema.sql` - OpenAPI schema with embedded JSON spec
+   - `types/` - Type definitions
+   - Backend functions: `get_nft_instances.sql`, `get_nft_types.sql`, `get_nft_instances_with_tags.sql`
+
+3. **Container Infrastructure**
+   - Main image: PostgreSQL client for schema installation and block processing
+   - Rewriter image: OpenResty/Nginx reverse proxy with URL rewriting
+
+### Data Flow
+```
+HAF → Block processing → nfttracker_app.main() → DB → PostgREST → Nginx rewriter → REST API
+```
+
+### Key Schemas
+- `nfttracker_app` - Main application schema with NFT tables and logic
+- Entry point: `nfttracker_app.main()` processes blocks
+
+## CI/CD
+
+GitLab CI builds two Docker images:
+- Main image: `registry.gitlab.syncad.com/hive/nft_tracker`
+- Rewriter image: `registry.gitlab.syncad.com/hive/nft_tracker/postgrest-rewriter`
+
+Branches `develop` and release tags (`vX.Y.Z`) get pushed to registries.
+
+## Testing Notes
+
+- Tests use pg_regress framework
+- Test database: `nft_regression_test`
+- Expected output: `tests/regression/expected/*.out`
+- Actual results: `tests/regression/results/*.out`
+- When tests fail, diff the expected vs results files
+
+## Key Files
+
+- `rewrite_rules.conf` - Nginx URL rewrites (REST paths → PostgREST RPC)
+- `docker/nft_tracker_nginx.conf.template` - Nginx configuration
+- `haf/` - HAF submodule (git submodule)
-- 
GitLab