# CLAUDE.md

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

## Project Overview

FOAF.ex is an Elixir implementation of the [FOAF (Friend of a Friend)](http://xmlns.com/foaf/spec/) vocabulary, part of the [RDF.ex ecosystem](https://rdf-elixir.dev). It provides:

- An `RDF.Vocabulary.Namespace` for FOAF terms (via `FOAF.NS.FOAF`, delegated through the `FOAF` module using `act_as_namespace`)
- Grax schema structs for all FOAF classes with typed property mappings

## Common Commands

```sh
mix test                          # Run all tests
mix test test/foaf_test.exs       # Run a specific test file
mix test test/foaf_test.exs:45    # Run a specific test by line number
mix format                        # Format code
mix credo                         # Lint
mix dialyzer                      # Type checking (slow first run, builds PLT)
mix check                         # Full CI check: clean, deps, compile, format, test, credo
```

For local development against sibling RDF.ex packages:
```sh
RDF_EX_PACKAGES_SRC=LOCAL mix test
```

## Architecture

### Vocabulary Namespace

`FOAF.NS` (`lib/foaf/ns.ex`) defines the RDF vocabulary namespace from `priv/foaf.ttl`. The top-level `FOAF` module (`lib/foaf.ex`) delegates to `FOAF.NS.FOAF` via `act_as_namespace`, so callers use `FOAF.name()`, `FOAF.Person`, etc. directly.

### Grax Schema Hierarchy

All schemas use `Grax.Schema` with inheritance via `schema Child < Parent`:

```
FOAF.Thing              (base - general properties like name, phone, homepage)
├── FOAF.Agent          (nick, mbox, accounts, interests, etc.)
│   ├── FOAF.Person
│   ├── FOAF.Group
│   └── FOAF.Organization
├── FOAF.Document       (topic, sha1)
│   ├── FOAF.Image
│   └── FOAF.PersonalProfileDocument
├── FOAF.OnlineAccount  (account_name, account_service_homepage)
│   ├── FOAF.OnlineChatAccount
│   ├── FOAF.OnlineEcommerceAccount
│   └── FOAF.OnlineGamingAccount
└── FOAF.Project
```

Properties use `property` for literal/IRI values and `link` for references to other Grax schemas.

### Testing

Tests use `FOAF.Test.Case` (`test/support/foaf_case.ex`) which provides RDF imports, an `EX` test namespace for example IRIs, and common aliases. The main test generates test cases for every FOAF vocabulary term to verify namespace compatibility.

## Key Dependencies

- `rdf` (~> 2.0) - Core RDF data structures and vocabulary namespace support
- `grax` (~> 0.5) - Schema DSL for mapping RDF to Elixir structs