# insights-ai

AI agents network for the Orchard Insights platform. Provides system-wide context, per-service guidance, and cross-service development patterns for Claude Code and other AI assistants.

## Directory Layout Requirement

**CRITICAL:** `insights-ai` must be a **sibling directory** alongside all service repositories under a common parent (e.g., `Sony/`, `~/projects/`, etc.).

```
<parent>/                        # e.g., Sony/
├── insights-ai/                 # THIS REPO — must be here
├── frontend-insights/
├── orchard-suite/
├── graphql-router/
├── graphql-analytics/
├── graphql-knowledge-search/
├── graphql-knowledge/
├── graphql-product/
├── graphql-user/
├── ows-analytics/
├── ows-charts/
├── ows-playlist/
└── dbt-analytics/
```

Why? `setup.sh`, `sync.sh`, and cross-service scripts rely on sibling directory layout via `$(dirname "$SCRIPT_DIR")` as the parent. Placing `insights-ai` elsewhere will break symlink paths and dependency resolution.

## Quick Start

```bash
# Symlink CLAUDE.md files into each service repository
chmod +x setup.sh
./setup.sh

# Preview what would be done without making changes
./setup.sh --dry-run

# Remove all symlinks
./setup.sh --remove
```

## Structure

```
insights-ai/
├── CLAUDE.md               # Root: full system architecture & agent routing
├── setup.sh                # Symlink CLAUDE.md files into service repos
│
├── services/               # Per-service CLAUDE.md files (12 total)
│   ├── frontend-insights.md        # (pointer — has own CLAUDE.md)
│   ├── orchard-suite.md
│   ├── graphql-analytics.md        # (pointer — has own CLAUDE.md)
│   ├── graphql-knowledge-search.md
│   ├── graphql-knowledge.md
│   ├── graphql-product.md
│   ├── graphql-user.md
│   ├── graphql-router.md
│   ├── ows-analytics.md
│   ├── ows-charts.md
│   ├── ows-playlist.md
│   └── dbt-analytics.md
│
├── agents/                 # Custom agent definitions (7 total)
│   ├── graphql-service.md  # Any graphql-* Node.js service
│   ├── ows-service.md      # Any ows-* Python service
│   ├── dbt-service.md      # dbt-analytics SQL/Python
│   ├── frontend-service.md # Frontend React/TS work
│   ├── router-service.md   # graphql-router (Rust)
│   ├── cross-service.md    # End-to-end feature work
│   └── schema-reviewer.md  # GraphQL schema changes
│
├── rules/                  # Shared conventions (4 total)
│   ├── graphql-patterns.md # @theorchard GraphQL conventions
│   ├── ows-patterns.md     # OWS Python conventions
│   ├── dbt-patterns.md     # dbt-analytics conventions
│   └── federation-patterns.md
│
└── templates/              # Development checklists (4 total)
    ├── new-graphql-field.md    # Adding a GraphQL field end-to-end
    ├── new-ows-endpoint.md     # Adding an OWS REST endpoint
    ├── new-dbt-model.md        # Adding a dbt model
    └── new-component.md        # Adding a React component
```

## Services Covered

| Service | Type | Language |
|---------|------|----------|
| frontend-insights | Frontend | React / TypeScript |
| orchard-suite | Frontend (Monorepo) | React / TypeScript |
| graphql-analytics | GraphQL Backend | Node.js / TypeScript |
| graphql-knowledge-search | GraphQL Backend | Node.js / TypeScript |
| graphql-knowledge | GraphQL Backend | Node.js / TypeScript |
| graphql-product | GraphQL Backend | Node.js / TypeScript |
| graphql-user | GraphQL Backend | Node.js / TypeScript |
| graphql-router | Federation Gateway | Rust |
| ows-analytics | Data Access Layer | Python / Flask |
| ows-charts | Data Access Layer | Python / Flask |
| ows-playlist | Data Access Layer | Python / Flask |
| dbt-analytics | Data Transformation | dbt / Python |

## How It Works

1. **`setup.sh`** creates symlinks from each service's `CLAUDE.md` to the corresponding file in `services/`
2. When Claude Code opens a service directory, it reads the symlinked `CLAUDE.md` for service-specific context
3. Services that already have their own `CLAUDE.md` (frontend-insights, graphql-analytics) are not overwritten
4. The root `CLAUDE.md` provides cross-service architecture context when working from the `insights-ai/` directory

## Updating

When service tech stacks change:
1. Update the relevant file in `services/`
2. All symlinked repos automatically get the update
3. No PRs needed in each service repo