# Development Guide

## Project Structure

```
pgmorbac/
├── src/                    # Modular SQL source files
├── tests/                  # Test files
├── tools/                  # Build and test scripts
├── docs/                   # Documentation
├── pgmorbac.control       # Version source of truth
├── pgmorbac.sql          # Generated (git-ignored)
└── Makefile               # Build automation
```

## Version Management

Version is defined in `pgmorbac.control` under `default_version`.

Edit source files in `src/` and commit them. Never edit or commit `pgmorbac.sql` (generated by build script).

## Development Workflow

### Edit Source Files

```bash
vim src/authorization.sql
```

### Build and Test

```bash
make test
```

This builds from `src/`, creates a temporary database, runs all tests, and cleans up.

### Commit Changes

```bash
git add src/authorization.sql tests/01_authorization.sql
git commit -m "Add feature X"
```

The build script concatenates `src/` files in dependency order (header first, footer last).

## Manual Testing

```bash
make build
createdb mytest
psql -d mytest -f pgmorbac.sql
psql -d mytest
dropdb mytest
```

## Release Process

1. Update version in `pgmorbac.control`
2. Update `CHANGELOG.md`
3. Run `make build` and `make test`
4. Commit and tag:

```bash
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags
```

## Makefile Targets

```bash
make build      # Build from src/ files
make test       # Build and run tests
make install    # Install to PostgreSQL
make help       # Show all targets
```

## Code Style

SQL keywords in UPPERCASE. Identifiers in lowercase_snake_case. Always qualify with `morbac.` schema.

Functions use `verb_noun` pattern. Tables use plural nouns.

## Adding Features

1. Edit files in `src/`
2. Add tests in `tests/`
3. Update `docs/DOCUMENTATION.md`
4. Run `make test`
5. Commit source files

## Debugging

```sql
SELECT * FROM morbac.auth_cache ORDER BY last_checked DESC LIMIT 10;
SELECT morbac.invalidate_auth_cache();
EXPLAIN ANALYZE SELECT morbac.is_allowed(...);
SELECT morbac.refresh_hierarchy_cache();
```

## Resources

See [DOCUMENTATION.md](DOCUMENTATION.md), [PERFORMANCE.md](PERFORMANCE.md), and [ADMIN_GUIDE.md](ADMIN_GUIDE.md).