# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

RelSpec is a database relations specification tool that provides bidirectional conversion between various database schema formats. It reads database schemas from multiple sources and writes them to various formats.

**Supported Readers:** Bun, DBML, DCTX, DrawDB, Drizzle, GORM, GraphQL, JSON, MSSQL, PostgreSQL, Prisma, SQL Directory, SQLite, TypeORM, YAML

**Supported Writers:** Bun, DBML, DCTX, DrawDB, Drizzle, GORM, GraphQL, JSON, MSSQL, PostgreSQL, Prisma, SQL Exec, SQLite, Template, TypeORM, YAML

## Build Commands

```bash
# Build the binary
make build              # Outputs to build/relspec
go build -o build/relspec ./cmd/relspec

# Run tests
make test              # Run all tests with race detection and coverage
go test ./...          # Run tests without coverage

# Run a single test
go test -run TestName ./pkg/readers/dbml

# Linting
make lint              # Requires golangci-lint installed

# Coverage report
make coverage          # Generates coverage.html

# Clean build artifacts
make clean

# Install binary
make install           # Installs to $GOPATH/bin
```

## Architecture

### Core Data Model (pkg/models/)

The central data structure is the `Database` model, which represents a complete database schema with this hierarchy:

```
Database
└── Schemas ([]Schema)
    └── Tables ([]Table)
        ├── Columns (map[string]Column)
        ├── Constraints (map[string]Constraint)
        ├── Indexes (map[string]Index)
        └── Relationships (map[string]Relationship)
```

**Important patterns:**
- Each format has its own `pkg/readers/<format>/` and `pkg/writers/<format>/` subdirectories
- Use `ReaderOptions` and `WriterOptions` structs for configuration (file paths, connection strings, metadata, flatten option)
- FlattenSchema option collapses multi-schema databases into a single schema for simplified output
- Schema reading typically returns the first schema when reading from Database
- Table reading typically returns the first table when reading from Schema

### Transformation Layer (pkg/transform/)

The `Transformer` provides validation and normalization utilities. Note: validation methods are currently stubs (return nil) and need implementation when used.

### Database-Specific Utilities (pkg/pgsql/)

Contains PostgreSQL-specific helpers:
- `keywords.go`: SQL reserved keywords validation
- `datatypes.go`: PostgreSQL data type mappings and conversions

### Additional Utilities

- **pkg/diff/**: Schema difference detection and comparison
- **pkg/inspector/**: Schema inspection and analysis tools
- **pkg/merge/**: Schema merging capabilities
- **pkg/reflectutil/**: Reflection utilities for dynamic type handling
- **pkg/ui/**: Terminal UI components for interactive schema editing
- **pkg/commontypes/**: Shared type definitions

## Development Patterns

- Each reader/writer is self-contained in its own subdirectory
- Options structs control behavior (file paths, connection strings, flatten schema, etc.)
- Live database connections supported for PostgreSQL and SQLite
- Template writer allows custom output formats

## Testing

- Test files should be in the same package as the code they test
- Use table-driven tests for multiple test cases
- All tests run with race detection via `make test`
- Coverage reports available via `make coverage`

## Module Information

- Module path: `git.warky.dev/wdevs/relspecgo`
- Go version: 1.24.0
- Uses Cobra for CLI
- Key dependencies: pgx/v5 (PostgreSQL), modernc.org/sqlite (SQLite), tview (TUI), Bun ORM