# Integrations Module – Agent Instructions

## Module Identity

**Module:** Integrations  
**Purpose:** Canonical integration catalog for registries, SCM providers, CI systems, repo sources, and runtime hosts.  
**Deployable:** `src/Integrations/StellaOps.Integrations.WebService`

---

## Directory Layout

```
src/Integrations/
├── StellaOps.Integrations.WebService/       # ASP.NET Core host
├── __Libraries/
│   ├── StellaOps.Integrations.Core/         # Domain models, enums, events
│   ├── StellaOps.Integrations.Contracts/    # Plugin contracts and DTOs
│   ├── StellaOps.Integrations.Plugins.Abstractions/  # IIntegrationConnectorPlugin
│   ├── StellaOps.Integrations.Persistence/  # PostgreSQL repositories
│   └── StellaOps.Integrations.Testing/      # Shared test fixtures
├── __Plugins/
│   ├── StellaOps.Integrations.Plugin.GitHubApp/
│   ├── StellaOps.Integrations.Plugin.GitLab/
│   ├── StellaOps.Integrations.Plugin.Harbor/
│   ├── StellaOps.Integrations.Plugin.Ecr/
│   ├── StellaOps.Integrations.Plugin.Gcr/
│   ├── StellaOps.Integrations.Plugin.Acr/
│   └── StellaOps.Integrations.Plugin.InMemory/  # Testing / dev
└── __Tests/
    └── StellaOps.Integrations.Tests/
```

---

## Roles & Responsibilities

| Role | Expectations |
| --- | --- |
| Backend Engineer | Implement core catalog, plugin loader, API endpoints, event publisher |
| Plugin Author | Implement `IIntegrationConnectorPlugin` for new providers |
| QA Engineer | Cover plugin loading, test-connection, health polling, CRUD scenarios |
| PM/Architect | Keep plugin contracts stable; coordinate cross-module dependencies |

---

## Plugin Contract

All connectors implement `IIntegrationConnectorPlugin : IAvailabilityPlugin`:

```csharp
public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
    IntegrationType Type { get; }
    IntegrationProvider Provider { get; }
    Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
    Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
}
```

---

## Required Reading

- `docs/modules/platform/architecture-overview.md`
- `docs/architecture/integrations.md`
- `docs/modules/authority/architecture.md` (AuthRef handling)

---

## Constraints

1. **No raw secrets:** All credentials use AuthRef URIs resolved at runtime.
2. **Determinism:** Stable ordering in listings; UTC timestamps.
3. **Offline-first:** All plugin test-connection and health must handle network failure gracefully.
4. **Event emission:** Lifecycle events go to Scheduler/Signals via message queue.

---

## Test Coverage

- Unit tests in `__Tests/StellaOps.Integrations.Tests`
- Each plugin has its own test class mocking external APIs
- Integration tests use `StellaOps.Integrations.Plugin.InMemory`