dcatr

# GEMINI.md - DCAT-R.ex Project Context

This document provides foundational mandates and context for Gemini CLI when working on the `DCAT-R.ex` project.

## Project Overview

**DCAT-R.ex** is an Elixir framework for building specialized data services over RDF repositories. It extends the W3C DCAT vocabulary to provide a standardized infrastructure for organizing RDF graphs into a hierarchical structure, enabling services like versioning (e.g., Ontogen), validation, and inference.

### Core Architecture: The 4-Layer Hierarchy

DCAT-R organizes RDF data through four disjoint catalog layers:

1.  **Service (`DCATR.Service`)**: The operations layer (runtime configuration). Combines local data with a shared repository.
2.  **ServiceData (`DCATR.ServiceData`)**: The **local** data catalog. Contains instance-specific data (manifests, working graphs, local caches) that is **never distributed**.
3.  **Repository (`DCATR.Repository`)**: The **distributable** data catalog. Contains the primary dataset, repository metadata, and shared system graphs (history, provenance).
4.  **Dataset (`DCATR.Dataset`)**: The pure user data catalog. A collection of `DataGraph`s and `DCATR.Directory`s for hierarchical organization, always distributed within a repository.

### Graph Taxonomy

Every graph in DCAT-R belongs to exactly one of these classes:
- **`DataGraph`**: Primary user content.
- **`ManifestGraph`**: Configuration data (`RepositoryManifestGraph` or `ServiceManifestGraph`).
- **`SystemGraph`**: Infrastructure data (distributed history or local caches).
- **`WorkingGraph`**: Temporary/draft data for local operations.

## Development & Build Commands

- **Install Dependencies**: `mix deps.get` (Note: `RDF_EX_PACKAGES_SRC=LOCAL` is used for local RDF.ex development, typically set via `.envrc` and `direnv`).
- **Compile**: `mix compile` (use `--warnings-as-errors` for strict checks).
- **Test**: `mix test`
- **Comprehensive Check**: `mix check` (runs clean, compile, format check, tests, and credo).
- **Interactive Console**: `iex -S mix`
- **Format Code**: `mix format`
- **Linting**: `mix credo`

## Engineering Standards & Conventions

### Directory & Module Naming
- **Convention**: This project uses subdirectories for organization without reflecting them in the module namespace.
- **Example**: Files in `lib/dcatr/model/` (e.g., `service.ex`) define modules in the `DCATR` namespace (e.g., `defmodule DCATR.Service`), **not** `DCATR.Model.Service`.
- **Manifests**: Files in `lib/dcatr/manifest/` *do* use the `DCATR.Manifest` namespace.

### Coding Style
- **RDF Integration**: Uses `RDF.ex` for data modeling and `Grax` for mapping RDF to Elixir structs.
- **Namespaces**: Vocabulary namespaces are defined in `lib/dcatr/ns.ex`.
- **Error Handling**: Use structured exception structs defined in `lib/dcatr/exceptions.ex`. Return `{:error, %Exception{}}` tuples.
- **Documentation**: Focus on "why" rather than "what". Use `## Options` and `## Examples` sections.

### Testing Strategy: Exact-First Testing
- **Mandate**: Use exact comparisons (`==`) with complete structs as the default.
- **Order**: Expected values on the right side of `==`.
- **Setup**: Use `setup` scenarios and factories from `test/support/test_factories.ex`.
- **Factories**: Use `example_*_scenario` functions to populate test context with predictable IDs.

### Source Control
- **Commits**: Capitalized verb, no prefix, under 80 characters (e.g., "Add DCAT-R vocabulary definitions").

## Key Files
- `mix.exs`: Project configuration and dependencies.
- `lib/dcatr.ex`: Main entry point and core conceptual documentation.
- `priv/vocabs/dcatr.ttl`: The formal DCAT-R vocabulary definition.
- `CLAUDE.md`: Detailed technical guide for AI assistants.
- `magma/`: Knowledge base and development documentation.


## Respond-in-file Rule

When instructed to apply the respond-in-file rule with a specific file path:
1. **Write response to specified file** using Edit tool
    - Start with `## Response: ` followed by a descriptive title
    - Do not use any `---` delimiters
    - Otherwise, content identical to what would be written in chat
2. **Never output main response in chat** - always use Edit tool
3. **Post-response**: Return to conversation and confirm completion