---
to: "generated/docs/{{ name | snake }}.md"
vars:
  name: "{{ name }}"
  format: "{{ format }}"
  style: "{{ style }}"
prefixes:
  ex: "http://example.org/advanced-rust-project/"
base: "http://example.org/advanced-rust-project/"
rdf:
  - "data/domain.ttl"
sparql:
  find_entities: "SELECT ?entity WHERE { ?entity a ex:Entity }"
  find_endpoints: "SELECT ?endpoint WHERE { ?endpoint a ex:Endpoint }"
  find_tables: "SELECT ?table WHERE { ?table a ex:Table }"
  find_relationships: "SELECT ?rel WHERE { ?rel a ex:Relationship }"
---

# {{ name | title }} Documentation

Generated by ggen on {{ "now" | date(format="%Y-%m-%d %H:%M:%S") }}

## Overview

This document provides comprehensive documentation for the {{ name | title }} system, including:

- **Domain Model**: {{ sparql_count(results=sparql_results.find_entities) }} entities
- **API Endpoints**: {{ sparql_count(results=sparql_results.find_endpoints) }} endpoints  
- **Database Tables**: {{ sparql_count(results=sparql_results.find_tables) }} tables
- **Relationships**: {{ sparql_count(results=sparql_results.find_relationships) }} relationships

## Domain Model

### Entities

{% for entity in sparql_results.find_entities %}
{% set entity_name = entity.entity | local %}
{% set entity_label = entity_name | title %}

#### {{ entity_label }}

- **Type**: {{ entity.entity }}
- **Label**: {{ entity_label }}
- **Properties**: 
  {% for prop in sparql_results.find_properties %}
  {% if prop.entity == entity.entity %}
  - {{ prop.property | local | title }}
  {% endif %}
  {% endfor %}
- **Relationships**:
  {% for rel in sparql_results.find_relationships %}
  {% if rel.fromEntity == entity.entity %}
  - {{ rel.rel | local | title }} → {{ rel.toEntity | local | title }}
  {% endif %}
  {% endfor %}

{% endfor %}

## API Endpoints

### Endpoint Summary

| Method | Path | Description | Requires Auth |
|--------|------|-------------|---------------|
{% for endpoint in sparql_results.find_endpoints %}
{% set method = sparql_first(results=sparql_results.find_methods, column="method") %}
{% set path = sparql_first(results=sparql_results.find_paths, column="path") %}
{% set description = endpoint.description | default("No description") %}
{% set requires_auth = endpoint.requiresAuth | default("false") %}
| {{ method }} | {{ path }} | {{ description }} | {{ requires_auth }} |
{% endfor %}

### Detailed Endpoint Documentation

{% for endpoint in sparql_results.find_endpoints %}
{% set endpoint_name = endpoint.endpoint | local %}
{% set method = sparql_first(results=sparql_results.find_methods, column="method") %}
{% set path = sparql_first(results=sparql_results.find_paths, column="path") %}

#### {{ endpoint_name | title }}

- **Method**: {{ method }}
- **Path**: {{ path }}
- **Description**: {{ endpoint.description | default("No description available") }}
- **Requires Authentication**: {{ endpoint.requiresAuth | default("false") }}

**Request/Response Types**:
- **Request**: {{ endpoint.requestType | default("N/A") }}
- **Response**: {{ endpoint.responseType | default("N/A") }}

**Example Request**:
```json
{
  "name": "example",
  "description": "Example request"
}
```

**Example Response**:
```json
{
  "id": "123",
  "name": "example",
  "description": "Example response",
  "created_at": "{{ "now" | date(format="%Y-%m-%d %H:%M:%S") }}",
  "updated_at": "{{ "now" | date(format="%Y-%m-%d %H:%M:%S") }}"
}
```

{% endfor %}

## Database Schema

### Table Overview

| Table Name | Description | Columns |
|------------|-------------|---------|
{% for table in sparql_results.find_tables %}
{% set table_name = table.table | local %}
{% set table_label = table_name | title %}
{% set column_count = sparql_count(results=sparql_results.find_columns) %}
| {{ table_name }} | {{ table_label }} | {{ column_count }} |
{% endfor %}

### Detailed Table Documentation

{% for table in sparql_results.find_tables %}
{% set table_name = table.table | local %}
{% set table_label = table_name | title %}

#### {{ table_label }} Table

**Table Name**: `{{ table_name }}`

**Columns**:
{% for column in sparql_results.find_columns %}
{% if column.table == table.table %}
{% set column_name = column.column | local %}
{% set data_type = column.dataType %}
{% set is_primary = column.isPrimaryKey | default("false") %}
{% set is_unique = column.isUnique | default("false") %}
{% set is_not_null = column.isNotNull | default("false") %}
{% set default_value = column.defaultValue | default("") %}

- **{{ column_name | title }}** (`{{ column.columnName }}`)
  - **Type**: {{ data_type }}
  - **Primary Key**: {{ is_primary }}
  - **Unique**: {{ is_unique }}
  - **Not Null**: {{ is_not_null }}
  {% if default_value %}
  - **Default**: {{ default_value }}
  {% endif %}

{% endif %}
{% endfor %}

**Indexes**:
{% for column in sparql_results.find_columns %}
{% if column.table == table.table and column.isUnique == "true" %}
- `idx_{{ table_name }}_{{ column.columnName }}` (UNIQUE)
{% endif %}
{% endfor %}

**Foreign Keys**:
{% for column in sparql_results.find_columns %}
{% if column.table == table.table and column.isForeignKey %}
- `{{ column.columnName }}` → `{{ column.isForeignKey | local }}`
{% endif %}
{% endfor %}

{% endfor %}

## Relationships

### Relationship Overview

| From Entity | Relationship | To Entity | Cardinality |
|-------------|--------------|-----------|-------------|
{% for rel in sparql_results.find_relationships %}
{% set from_entity = rel.fromEntity | local | title %}
{% set rel_name = rel.rel | local | title %}
{% set to_entity = rel.toEntity | local | title %}
{% set cardinality = rel.cardinality | default("N:N") %}
| {{ from_entity }} | {{ rel_name }} | {{ to_entity }} | {{ cardinality }} |
{% endfor %}

### Detailed Relationship Documentation

{% for rel in sparql_results.find_relationships %}
{% set rel_name = rel.rel | local %}
{% set from_entity = rel.fromEntity | local %}
{% set to_entity = rel.toEntity | local %}
{% set cardinality = rel.cardinality | default("N:N") %}

#### {{ rel_name | title }}

- **From Entity**: {{ from_entity | title }}
- **To Entity**: {{ to_entity | title }}
- **Cardinality**: {{ cardinality }}
- **Description**: {{ rel.description | default("No description available") }}

**Implementation Notes**:
- This relationship is implemented as a foreign key constraint
- The relationship supports cascading operations
- Indexes are created for optimal query performance

{% endfor %}

## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | Database connection string | `postgresql://localhost/{{ name | snake }}` | Yes |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` | No |
| `LOG_LEVEL` | Logging level | `info` | No |
| `PORT` | Server port | `8080` | No |
| `HOST` | Server host | `0.0.0.0` | No |

### Configuration Files

#### ggen.toml
```toml
[project]
name = "{{ name | snake }}"
version = "1.0.0"
description = "{{ name | title }} system"

[ai]
provider = "openai"
model = "gpt-4"
temperature = 0.7

[rdf]
base_iri = "http://example.org/{{ name | snake }}/"
default_format = "turtle"
```

#### make.toml
```toml
[lifecycle.init]
description = "Initialize project"
commands = ["cargo init", "mkdir -p src/api"]

[lifecycle.build]
description = "Build project"
commands = ["cargo build --release"]
depends_on = ["init"]
```

## Usage Examples

### Basic Usage

```bash
# Initialize project
ggen lifecycle run init

# Generate code
ggen template generate templates/rust-service.tmpl

# Build project
ggen lifecycle run build

# Run tests
ggen lifecycle run test
```

### Advanced Usage

```bash
# Generate with AI
ggen ai generate --description "Rust microservice with REST API"

# Generate SPARQL queries
ggen ai sparql --description "Find all API endpoints"

# Generate RDF graphs
ggen ai graph --description "E-commerce domain model"

# Run pipeline
ggen lifecycle pipeline setup generate build test deploy
```

### Template Usage

```rust
// Use generated service
use {{ name | snake }}_service::{{ name | pascal }}Service;

let service = {{ name | pascal }}Service::new(config);
let app = service.router();
```

## Testing

### Unit Tests

```bash
# Run unit tests
cargo test

# Run with coverage
cargo test -- --nocapture
```

### Integration Tests

```bash
# Run integration tests
cargo test --test integration

# Run with database
DATABASE_URL=postgresql://localhost/test_db cargo test
```

### End-to-End Tests

```bash
# Run E2E tests
cargo test --test e2e

# Run with real services
cargo test --test e2e -- --test-threads=1
```

## Deployment

### Development

```bash
# Start development server
cargo run --bin {{ name | snake }}

# Start with hot reload
cargo watch -x run
```

### Staging

```bash
# Deploy to staging
ggen lifecycle run deploy --env staging
```

### Production

```bash
# Deploy to production
ggen lifecycle run deploy --env production
```

## Monitoring

### Health Checks

```bash
# Check service health
curl http://localhost:8080/health

# Check metrics
curl http://localhost:8080/metrics
```

### Logging

```bash
# View logs
tail -f logs/{{ name | snake }}.log

# Filter logs
grep "ERROR" logs/{{ name | snake }}.log
```

## Troubleshooting

### Common Issues

1. **Database Connection Failed**
   - Check `DATABASE_URL` environment variable
   - Verify database server is running
   - Check network connectivity

2. **Template Generation Failed**
   - Verify template syntax
   - Check RDF data files
   - Validate SPARQL queries

3. **Build Errors**
   - Check Rust toolchain version
   - Verify dependencies
   - Clean build cache

### Debug Mode

```bash
# Enable debug logging
RUST_LOG=debug cargo run

# Enable trace logging
RUST_LOG=trace cargo run
```

## Contributing

### Development Setup

1. Clone repository
2. Install dependencies
3. Run tests
4. Make changes
5. Submit pull request

### Code Style

- Follow Rust conventions
- Use `cargo fmt` for formatting
- Use `cargo clippy` for linting
- Write comprehensive tests

### Documentation

- Update README.md
- Add code comments
- Write API documentation
- Include usage examples

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Changelog

### Version 1.0.0

- Initial release
- Basic CRUD operations
- REST API endpoints
- Database schema
- Documentation

---

*Generated by ggen on {{ "now" | date(format="%Y-%m-%d %H:%M:%S") }}*
