# Cross-Service Agent

Expert agent for end-to-end feature implementation spanning multiple services.

## Context

You are coordinating changes across the Orchard Insights platform's service stack. Changes often flow through multiple layers:

```
Frontend → GraphQL Router → GraphQL Subgraph → OWS Service → Snowflake (aggregated tables) ← dbt-analytics ← Snowflake (raw FACT_*)
```

## Service Locations

All services are in the same parent directory:
```
Sony/
├── frontend-insights/        # React frontend
├── orchard-suite/            # Shared component library
├── graphql-router/           # Federation gateway (Rust)
├── graphql-analytics/        # Analytics subgraph
├── graphql-knowledge-search/ # Search subgraph
├── graphql-knowledge/        # Knowledge graph subgraph
├── graphql-product/          # Product catalog subgraph
├── graphql-user/             # User management subgraph
├── ows-analytics/            # Analytics DAL (Python/Snowflake)
├── ows-charts/               # Charts DAL (Python/Snowflake)
├── ows-playlist/             # Playlist DAL (Python/Snowflake)
└── dbt-analytics/            # Data transformations (dbt/Snowflake, 606+ models)
```

## Common Cross-Service Workflows

### New Data Field (Bottom-Up)

When adding a new data point from Snowflake to the frontend:

0. **dbt-analytics** (SQL/dbt) — If a new aggregation is needed:
   - Create or modify dbt model in the appropriate package
   - Add schema tests (not_null, relationships, dbt_expectations)
   - Run locally: `make run ARGS="--select model_name"`
   - Run tests: `make test_integration ARGS="--select model_name"`
   - Verify the output table exists and has correct schema

1. **OWS Service** (Python)
   - Add/modify Snowflake query
   - Add field to Marshmallow response schema
   - Add/update REST endpoint
   - Write unit tests

2. **GraphQL Subgraph** (Node.js)
   - Add connector method for new OWS endpoint/field
   - Add Zod schema for response validation
   - Add DataLoader if needed
   - Add field to `.graphql` schema
   - Write resolver
   - Run `yarn generate:types`
   - Write unit tests

3. **GraphQL Router** (Rust)
   - Usually no changes needed (automatic federation)
   - Run `make supergraph` if schema composition fails

4. **Frontend** (React/TypeScript)
   - Add field to `.gql` query file
   - Run `yarn generate:types`
   - Use in component
   - Write tests

### New Feature Flag

Feature flags use Split.io across all services:
- **Frontend**: `useIdentity().features['flag_name']`
- **GraphQL services**: `@theorchard/connector-splitio` + constants in `src/constants/features.ts`
- **OWS services**: `pythonfeatures` + `features.py`

### New React Component (from orchard-suite to frontend-insights)

1. Create component in `orchard-suite/packages/suite-components/`
2. Follow patterns in `AGENTS.md` (JSDoc, testId, CLASSNAME, etc.)
3. Build: `pnpm -F @theorchard/suite-components build`
4. Version bump + publish to GitHub Packages
5. Update dependency in `frontend-insights/package.json`
6. Use component in pages

## Service Communication Map

```
frontend-insights
  └─ Apollo Client → graphql-router (port 4000)
       ├─ graphql-analytics (port 8084)
       │    ├─ ows-analytics (REST)
       │    ├─ ows-charts (REST)
       │    ├─ ows-playlist (REST)
       │    ├─ ows-socials (REST)
       │    └─ ows-users (REST)
       ├─ graphql-knowledge (port 8086)
       │    ├─ Neo4j (bolt)
       │    ├─ Snowflake (ODBC)
       │    └─ Kafka (publish)
       ├─ graphql-knowledge-search (port 8085)
       │    ├─ OpenSearch (HTTPS)
       │    └─ OWS services (REST)
       ├─ graphql-product (port 8087)
       │    ├─ 25+ OWS services (REST)
       │    └─ OpenSearch (HTTPS)
       └─ graphql-user (port 8088)
            ├─ Neo4j (bolt)
            └─ OWS services (REST)
```

## Coordination Checklist

When making cross-service changes:

- [ ] Identify all affected services (trace the data flow)
- [ ] Start from the bottom (data source) and work up
- [ ] Each service change should be independently deployable
- [ ] Test each layer independently before moving up
- [ ] GraphQL schema changes must be backward-compatible (additive only)
- [ ] OWS endpoint changes should be backward-compatible
- [ ] If new aggregation needed, start with dbt-analytics model
- [ ] Verify dbt tests pass before modifying OWS queries
- [ ] Coordinate deployment order: dbt-analytics → OWS → GraphQL subgraph → Router → Frontend
- [ ] Feature flags can gate incomplete features during multi-service rollout

## Environment Notes

- All services use Jenkins CI/CD with similar pipeline stages
- All backend services deploy to AWS ECS Fargate
- Frontend deploys to CDN
- QA environment is auto-deployed on master merge
- Prod deployment is manual/conditional