Concepts
Architecture
A modular hexagonal monolith with explicit dependency wiring.
The repository is one Go module and one deployable binary. Its boundaries are intentional:
HTTP / MCP transports
│
▼
execution capabilities
│
▼
connector interfaces
│
▼
PostgreSQL · SQLite · MySQL adaptersPackage responsibilities
| Area | Responsibility |
|---|---|
cmd/dataporch | CLI commands, process startup, and local admin client commands. |
internal/app | Composition root; constructs services and mounts transports. |
internal/config | Reads and validates environment configuration. |
internal/execution | Discovery, query validation, authorization, pagination, limits, and error classification. |
internal/connection | Consumer-owned connector contracts and source definitions. |
internal/connection/postgres | PostgreSQL URL parsing, read-only pool behavior, discovery, and query execution. |
internal/connection/sqlite | Read-only SQLite opening, policy enforcement, discovery, and query execution. |
internal/connection/mysql | MySQL URL parsing, read-only pool behavior, discovery, and query execution. |
internal/transports/mcp | MCP tool schemas, authenticated Streamable HTTP, wire errors, and request bounds. |
internal/transports/localmcp | Authenticated local MCP server over an owner-only Unix socket with runtime-lifetime credentials. |
internal/transports/mcpstdio | Stdio proxy used by dataporch mcp to reach the local MCP server. |
internal/transports/localadmin | Unix-socket management for source import and direct HTTP MCP token lifecycle. |
internal/transports/httpapi | Public health endpoint. |
internal/mcpcontrol/local | Owner-only local MCP credential publication and cleanup. |
internal/secret | Local master key, encrypted stores, and token verifier storage. |
Core capability packages do not import HTTP, MCP, database drivers, or vendor SDKs. Transports and adapters depend inward on execution contracts. This keeps a new transport from creating a second validation path.
Composition root
Dependencies are built explicitly in internal/app. There is no dependency-injection framework, global registry, service locator, or package initialization side effect. Tests provide small fakes through consumer-owned interfaces, and production wiring remains visible and compile-time checked.
Request path
- A client reaches the shared MCP handler through direct HTTP bearer auth or the
dataporch mcpstdio-to-Unix-socket adapter. - The MCP transport validates the tool input and attaches the authenticated caller.
- Execution resolves the source, checks capability and authorization, and validates identifiers.
- The adapter opens the configured source under its own read-only policy.
- Execution applies timeout, row, and response-byte bounds.
- The transport serializes a stable result or a categorized failure.