> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Overview

> Architecture and development guide for Station contributors

# Contributing to Station

This section covers Station's internal architecture, development setup, and testing for contributors.

## Architecture Overview

Station is a **modular, service-oriented AI agent orchestration platform** built in Go.

### Four-Layer Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   CLI        │  │   API        │  │  MCP Server  │          │
│  │  (cmd/main)  │  │   (:8585)    │  │  (stdio)     │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
├─────────┼─────────────────┼─────────────────┼───────────────────┤
│         └─────────────────┼─────────────────┘                   │
│                           ▼                                      │
│                    SERVICE LAYER                                 │
│         ┌─────────────────────────────────┐                     │
│         │    43+ Focused Service Modules   │                     │
│         │    (internal/services/)          │                     │
│         └─────────────────┬───────────────┘                     │
├───────────────────────────┼─────────────────────────────────────┤
│                           ▼                                      │
│                   DATA ACCESS LAYER                              │
│         ┌─────────────────────────────────┐                     │
│         │    11 Repository Modules         │                     │
│         │    (internal/db/repositories/)   │                     │
│         └─────────────────┬───────────────┘                     │
├───────────────────────────┼─────────────────────────────────────┤
│                           ▼                                      │
│                  PERSISTENCE LAYER                               │
│         ┌──────────────────┐  ┌──────────────────┐              │
│         │  SQLite Database │  │  File System     │              │
│         │  (station.db)    │  │  (environments/) │              │
│         └──────────────────┘  └──────────────────┘              │
└─────────────────────────────────────────────────────────────────┘
```

### Unified Execution Engine

All entry points converge at the **AgentExecutionEngine**:

| Entry Point | Path                              | Handler                          |
| ----------- | --------------------------------- | -------------------------------- |
| CLI         | `stn agent run`                   | `cmd/main/handlers/agent/`       |
| API         | `POST /api/v1/agents/:id/execute` | `internal/api/v1/`               |
| MCP         | `call_agent` tool                 | `internal/mcp/`                  |
| Scheduler   | Cron trigger                      | `internal/services/scheduler.go` |

### Core Services

| Category       | Services                                                     |
| -------------- | ------------------------------------------------------------ |
| **Execution**  | AgentService, AgentExecutionEngine, GenKitProvider           |
| **MCP**        | MCPConnectionManager, MCPToolDiscovery, ToolDiscoveryService |
| **Config**     | DeclarativeSync, EnvironmentManagementService, AgentFileSync |
| **Scheduling** | SchedulerService                                             |
| **Telemetry**  | TelemetryService, DeploymentContextService                   |

## Repository Structure

```
station/
├── cmd/main/              # CLI entry point
│   └── handlers/          # CLI command handlers
├── internal/
│   ├── api/v1/            # REST API handlers
│   ├── config/            # Configuration loading
│   ├── db/                # Database layer
│   │   ├── repositories/  # Data access
│   │   └── schema.sql     # Database schema
│   ├── mcp/               # MCP server implementation
│   ├── services/          # Business logic (43+ modules)
│   └── workflows/         # Workflow engine
├── pkg/                   # Public packages
├── bundles/               # Agent bundles
└── docs/
    └── architecture/      # Detailed architecture docs
```

## Key Files

| Component       | Location                                      |
| --------------- | --------------------------------------------- |
| Agent execution | `internal/services/agent_execution_engine.go` |
| MCP management  | `internal/services/mcp_*.go`                  |
| Sync service    | `internal/services/declarative_sync.go`       |
| API handlers    | `internal/api/v1/*.go`                        |
| CLI handlers    | `cmd/main/handlers/`                          |
| Database schema | `internal/db/schema.sql`                      |
| MCP server      | `internal/mcp/server.go`                      |
| Config loading  | `internal/config/config.go`                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Setup" icon="laptop-code" href="/contributing/development">
    Set up your local development environment
  </Card>

  <Card title="Architecture Deep Dive" icon="sitemap" href="/contributing/architecture">
    Detailed diagrams and component analysis
  </Card>

  <Card title="Testing Guide" icon="flask" href="/contributing/testing">
    Running and writing tests
  </Card>

  <Card title="Code Style" icon="code" href="/contributing/code-style">
    Conventions and best practices
  </Card>
</CardGroup>