Codebase Structure

Top-level Layout

ud/
├── server.go                   # Entry point: Gorgany app init + provider registration
├── cmd/
│   └── modulescsv/main.go      # CLI: generates modules.csv catalog
├── pkg/                        # All application packages
├── storage/                    # Runtime data (gitignored in prod)
├── docs/                       # HTTP client files and API docs
├── .config.yaml                # Storage paths, allowed extensions, plugins
├── .env / .env.example         # Environment variables
├── config/config.yml           # Viper-managed runtime configuration
├── Dockerfile                  # Multi-stage production image
├── docker-compose.yml          # Production compose
├── docker-compose.dev.yml      # Development compose
└── docker-compose.local.yml    # Local debug (Delve + PostgreSQL)

Package Descriptions

`pkg/auth/`

Authentication strategies. Contains:

api_key.go — JWT-based API key validation (HS256, claims: userId/companyId/keyId/scopes)
oauth2.go — Microsoft OAuth2 flow (authorization URL, token exchange, user info fetch, auto-registration)
Session middleware integration with Gorgany

`pkg/cache/`

In-memory TTL cache shared across services. A single Cache struct with Get, Set, Delete, and Evict operations. TTL is checked on access and via the ClearTTLCache background job (runs every 1 minute). Used by: FlowService (flow definitions), TestCaseService, ModuleService (module catalog), AuditService (filter facets).

`pkg/cnst/`

All application constants and enums:

Play states: NEW, RUN, DONE, FAIL, SKIP, FILTERED, DEFERRED, WAIT, ON_HOLD
Permission names (8 company-level permissions)
Component kinds: storage, ai, db, request, console
Link types: oauth, basic, bearer, service_account
KV scope types: global, flow, flow_group

`pkg/components/`

Runtime capability implementations selected by the component system:

storage_*.go — Storage backends (local, S3, GCS, FTP)
ai_*.go — AI provider implementations (OpenAI, Claude, Mistral, Ollama)
db_*.go — Database drivers (MongoDB, PostgreSQL)
request.go — HTTP client component
test_*.go — Test mode components that record/replay external calls

`pkg/data/`

Data Transfer Objects (DTOs) used in HTTP request/response bodies. Separate from pkg/model/ which contains database models.

`pkg/error/`

Custom error types with HTTP status codes and error codes. Used by HTTP handlers to return consistent error responses.

`pkg/http/`

All REST API controllers, middleware, and command handlers:

controller_*.go — One file per resource (flows, plays, users, channels, kv, etc.)
middleware_*.go — Auth, CORS, audit logging, company context injection
command_*.go — Command pattern handlers for complex operations

`pkg/intf/`

Go interfaces for major platform abstractions. Referenced by components and services to enable swappable implementations.

`pkg/job/`

Gocron background jobs:

job_cache_audit_filters.go — Runs every 3 minutes, caches audit facet values
job_clear_ttl_cache.go — Runs every 1 minute, evicts expired cache entries

`pkg/logger/audit/`

Audit logging subsystem:

logger.go — Core audit logger with 7+ logging methods (LogIncomingRequest, LogEntityAction, LogAuthEvent, etc.)
sanitizer.go — Field sanitization rules per entity type (strips sensitive data, truncates large fields)

`pkg/mail/`

Email notification sending (for system alerts, not flow email modules). Uses SMTP config from alert.channel.email.

`pkg/mcp/`

Model Context Protocol server:

Starts on port 4445
Exposes flow8 operations as MCP tools for AI agent consumption
JWT authentication with mcp scope claim

`pkg/model/`

MongoDB document models (43+ structs). Each file contains one or more related model structs and their collection name constants. Key files:

model_flow.go — DBFlow, DBFlowlet (Layer), Filter
model_play.go — DBPlay, DBPlayLayer
model_company.go — DBCompany, DBCompanyUser, DBUserGroup
model_access.go — DBAccess
model_kv.go — DBKV
model_channel.go — DBChannel, DBChannelRoute, DBChannelRequest
model_link.go — DBLink
model_component.go — DBComponentConfig, DBInstallation, DBSystemConfig
model_schedule.go — Schedule
model_retention.go — DBRetentionPolicy
model_fixture.go — DBTestFixture, DBFlowTestSuite, DBFlowTestCase
model_ai.go — DBAISession, DBAIMessage, AiChat, AiChatMessage, AiGeneration

`pkg/plugin/`

Base plugin types used by all modules:

PluginModule struct (embedded by all module structs)
Params struct (passed to every Run() call)
Response builder pattern
KVUpdate struct for returning KV changes from modules

`pkg/plugins/layers/v2/`

All 135+ executable module implementations. Each file follows the naming convention module_<name>.go. Auto-discovered via Go reflection at startup.

`pkg/provider/`

Gorgany provider implementations that register services into the DI container:

provider_app.go — All application services (FlowService, PlayService, LayerService, etc.)
provider_route.go — HTTP route registration
provider_audit.go — Audit logger setup
provider_job.go — Background job registration
provider_db.go — MongoDB connection and initialization
provider_mcp.go — MCP server startup

`pkg/repo/`

SQLite-style query builder for MongoDB aggregation pipelines. Provides a fluent interface: Select, From, Where, OrderBy, Limit, Offset. Used to build consistent paginated list queries across all services.

`pkg/service/`

Business logic layer — 70+ service files. Key services:

File	Service	Purpose
`flow_service.go`	FlowService	Flow CRUD, execution trigger, caching
`play_service.go`	PlayService	Execution instance lifecycle management
`layer_service.go`	LayerService	Module-level execution within plays
`scheduler.go`	ScheduleService	Cron-based flow scheduling
`retention_policy_service.go`	RetentionPolicyService	Data cleanup, background job management
`ai_service.go`	AIService	Multi-provider AI orchestration
`ai_chat_service.go`	AIChatService	AI chat session management
`module_migration_service.go`	ModuleMigrationService	Module version tracking and migration
`test_fixture_service.go`	TestFixtureService	Fixture recording and replay
`flow_test_service.go`	FlowTestService	Test suite and test case management
`kv_service.go`	KVService	Key-value store operations
`channel_service.go`	ChannelService	Channel lifecycle and runtime
`link_service.go`	LinkService	OAuth2/API credential management
`component_service.go`	ComponentService	Runtime component resolution
`access_service.go`	AccessService	Permission checking and assignment
`user_service.go`	UserService	User account management
`company_service.go`	CompanyService	Tenant management

`pkg/utils/`

Shared utility functions: string manipulation, date formatting, hex encoding, type conversion helpers.

`pkg/websocket/`

WebSocket infrastructure:

hub.go — Connection hub managing all active WebSocket clients
client.go — Individual client connection with ping/pong keepalive (pingPeriod: 15s, readDeadline: 30s)
dispatcher.go — Routes execution events to subscribed clients by playId or companyId

Naming Conventions

Models: DB<EntityName> (e.g., DBFlow, DBPlay)
Services: <Entity>Service (e.g., FlowService, PlayService)
Controllers: controller_<resource>.go
Modules: module_<name>.go with struct Module<Name> and factory NewModule<Name>()
Jobs: job_<name>.go