Doc architecture
Agach orchestrates AI coding agents for your team. Define features through structured conversations. Agents execute the work in isolated environments, one task at a time, on your codebase.
npx -y skills add JLugagne/agach --skill doc-architectureAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Agach project hexagonal architecture: bounded contexts, source code hierarchy, entry points, layers, and package structure
SKILL.md
12.4 KB, ~2.7k tokens by cl100k_base, as published. Nobody here has run it
Agach Architecture — Hexagonal / Clean Architecture
Entry Points (cmd/)
cmd/agach-server/
main.go - HTTP + MCP server (port 8322, gorilla/mux, JWT auth, embedded React SPA)
config.go - YAML config loader (SSO settings, DaemonJWTTTL)
cmd/agach-daemon/main.go - Background daemon agent (Docker builds, chat sessions, git worktrees)
cmd/qa-seed/main.go - Seeds database with deterministic test data, outputs JSON IDs for Playwright
Backend — Hexagonal Architecture (internal/)
Each bounded context follows: domain/ → app/ → inbound/ + outbound/
internal/server/ — Core server bounded context
domain/
types.go - 11 ID types (ProjectID, TaskID, ColumnID, CommentID, FeatureID, SkillID,
DockerfileID, NotificationID, ChatSessionID, AgentID/RoleID, SpecializedAgentID)
- Enums: Priority, ColumnSlug, FeatureStatus, AuthorType,
NotificationSeverity, NotificationScope
- Structs: Project, Feature, Agent/Role, Skill, SpecializedAgent, Dockerfile,
Column, Task, Comment, TaskDependency, Notification, ChatSession,
ProjectSummary, ProjectWithSummary, FeatureWithTaskSummary, ProjectInfo,
TaskWithDetails, TokenUsage, ToolUsageStat, DependencyContext,
AgentColdStartStat, TimelineEntry, ModelTokenStat, ModelPricing, FeatureStats
errors.go - 60+ domain errors (ErrNotFound, ErrInvalidMove, etc.) using domainerror.Error
service/
commands.go - Command service interface (write operations) — composite of 8 sub-interfaces:
ProjectCommands, TaskCommands, AgentCommands, CommentCommands,
DependencyCommands, SkillCommands, FeatureCommands, DockerfileCommands,
NotificationCommands, SpecializedAgentCommands + top-level methods
queries.go - Query service interface (read operations) — composite of 8 sub-interfaces:
ProjectQueries, TaskQueries, AgentQueries, ColumnQueries, CommentQueries,
DependencyQueries, SkillQueries, FeatureQueries, DockerfileQueries,
NotificationQueries, StatsQueries, SpecializedAgentQueries
servicetest/contract.go - Service mock + contract tests
repositories/ - Repository interfaces + test contracts
tasks/ - TaskRepository (CRUD, GetNextTask, move, block, BulkCreate, BulkReassign, GetModelTokenStats)
columns/ - ColumnRepository (FindByID, FindBySlug, List, EnsureBacklog)
projects/ - ProjectRepository (CRUD, GetTree, GetSummary, CountChildren, ListModelPricing)
comments/ - CommentRepository (CRUD, Count, IsLastComment)
dependencies/ - DependencyRepository (CRUD, WouldCreateCycle, ListDependents, GetDependencyContext)
features/ - FeatureRepository (CRUD, UpdateStatus, GetStats)
agents/ - AgentRepository (composite: GlobalAgent + ProjectAgent + ScopedAgent repos)
skills/ - SkillRepository (CRUD, IsInUse, ListByAgent, AssignToAgent, RemoveFromAgent)
dockerfiles/ - DockerfileRepository (CRUD, IsInUse, SetLatest, Get/Set/ClearProjectDockerfile)
notifications/ - NotificationRepository (CRUD, UnreadCount, MarkRead, MarkAllRead)
toolusage/ - ToolUsageRepository (IncrementToolUsage, ListToolUsage)
specialized/ - SpecializedAgentRepository (CRUD, ListByParent, ListSkills, SetSkills)
chats/ - ChatSessionRepository (CRUD, FindByFeature, UpdateState, UpdateJSONLPath, UpdateTokenUsage)
Each has: <name>.go (interface) + <name>test/contract.go (mock + contract)
app/
app.go - Application service (wires 13 service structs via Config)
tasks.go - Task operations (create, bulk_create, move, block, complete, get_next, etc.)
columns.go - Column operations
comments.go - Comment operations
dependencies.go - Dependency operations (add, remove, cycle detection)
roles.go - Agent CRUD + clone + project assignment + bulk reassign
skills.go - Skill CRUD + agent assignment
dockerfiles.go - Dockerfile management + project dockerfile
prompt.go - Prompt template generation
agent_management.go - Agent lifecycle management
task_move_project.go - Cross-project task moves
tool_usage.go - Tool usage tracking
notifications.go - Notification CRUD + mark read
*_test.go - Unit tests using mock repositories
inbound/
commands/ - HTTP command handlers (POST/PUT/DELETE via gorilla/mux)
router.go - Route registration (13 handler groups)
tasks.go, comments.go, projects.go, roles.go, skills.go, features.go,
dockerfiles.go, project_agents.go, specialized_agents.go, notifications.go,
seen.go, images.go, chats.go
converters/ - Request/response type converters (API ↔ domain)
tasks.go, columns.go, comments.go, projects.go, roles.go, features.go,
skills.go, dockerfiles.go, notifications.go, timeline.go, tool_usage.go,
specialized_agents.go, cold_start_stats.go, chats.go, mapslice.go
queries/ - HTTP query handlers (GET via gorilla/mux)
router.go - Query route registration (17 handler groups)
tasks.go, projects.go, comments.go, dependencies.go, features.go,
roles.go, skills.go, dockerfiles.go, notifications.go, project_agents.go,
specialized_agents.go, sse.go, model_stats.go, cold_start_stats.go,
timeline.go, tool_usage.go, chats.go
outbound/
pg/ - PostgreSQL persistence (pgx/v5 + pgxpool)
pg.go - Main repository implementation
pg_skills.go - Skills SQL
pg_dockerfiles.go - Dockerfiles SQL
pg_notifications.go - Notifications SQL
pg_test.go - Integration tests (testcontainers + postgres:17)
migrations/ - SQL migration files (001-006)
qaseed/seed.go - QA test data seeder
init.go - Module initialization + DI wiring
internal/identity/ — Authentication bounded context
domain/
types.go - User, Team, Actor, DaemonActor, MemberRole (admin/member)
node.go - Node, OnboardingCode, NodeAccess, NodeID, NodeMode, NodeStatus
errors.go - ErrUnauthorized, ErrForbidden, ErrInvalidCredentials, ErrSSOUserNoPassword, etc.
ssoconfig.go - SsoProvider, OIDCConfig, SAMLConfig, SsoConfig
ttl.go - DefaultRefreshTokenTTL (7d), DefaultRememberMeTokenTTL (30d), DefaultDaemonJWTTTL (30d)
repositories/users/ - UserRepository (CRUD, FindByEmail, FindBySSO, ListByTeam)
repositories/teams/ - TeamRepository (CRUD, FindBySlug)
repositories/nodes/ - NodeRepository (CRUD, ListByOwner, ListActiveByOwner, UpdateLastSeen)
repositories/onboardingcodes/ - OnboardingCodeRepository (Create, FindByCode, MarkUsed, DeleteExpired)
repositories/nodeaccess/ - NodeAccessRepository (GrantUser/Team, RevokeUser/Team, ListByNode, HasAccess)
service/auth.go - AuthCommands + AuthQueries interfaces
service/teams.go - TeamCommands + TeamQueries interfaces
service/onboarding.go - OnboardingCommands interface
service/nodes.go - NodeCommands + NodeQueries interfaces
app/
auth.go - Auth logic (register, login, JWT, bcrypt cost 12, 15min access / 7-30d refresh)
sso.go - SSO/OIDC integration (discovery, code exchange, JWK validation)
teams.go - Team management (admin-only mutations)
onboarding.go - 6-digit code generation (15min expiry), node creation with refresh token
nodes.go - Node management (revoke, rename, access grants)
tokens.go - JWT issuance helpers (user + daemon tokens)
inbound/commands/
auth.go - Login/register/refresh/logout/profile (rate limited: 5/15min per IP)
sso.go - SSO providers list, OIDC authorize/callback with HMAC state
teams.go - Team CRUD, user role/team assignment
onboarding.go - Generate code, complete onboarding, daemon token refresh
nodes.go - Node list/get/revoke/rename/access
actor.go - ActorFromRequest helper (Bearer token → Actor)
outbound/pg/ - PostgreSQL persistence + migrations (001-002)
- pgp_sym_encrypt for sensitive columns
init.go - DI wiring, default admin seeding ([email protected]/admin)
internal/daemon/ — Daemon agent bounded context
domain/
types.go - OnboardingResult, ProjectInfo, DaemonState, BuildID, BuildStatus, DockerBuild
ports.go - ServerAuth, ServerOnboarding, ServerConnection, ProjectFetcher, ChatUploader interfaces
config/config.go - YAML config (.agach-daemon.yml), env vars (AGACH_ONBOARDING_CODE, AGACH_SERVER_URL)
app/
app.go - Main daemon loop (onboarding → WS connect → event handling)
tokens.go - Token persistence (~/.config/agach-daemon/tokens.json, 0600 perms)
chat.go - ChatManager: spawns Claude CLI processes, captures JSONL, uploads to server
30min TTL with 25min warning, stats broadcasting every 5s
docker.go - DockerService: list/rebuild/prune Docker images, SQLite build tracking
git.go - GitService: clone/fetch repos, SSH/HTTPS auth, worktree management
client/
auth.go - POST /api/daemon/refresh
onboarding.go - POST /api/onboarding/complete
projects.go - GET /api/projects/{id}
websocket.go - WS client with exponential backoff reconnect (1s-30s)
chat_upload.go - POST multipart JSONL upload
inbound/ws/
hub.go - Local WS hub for TUI clients
handlers.go - Docker list/rebuild/logs/prune handlers
types.go - HandlerFunc type
outbound/sqlite/
sqlite.go - SQLite DB + migrations
builds.go - DockerBuild repository (CRUD, DeleteNonLatest)
init.go - Daemon bootstrap (config → SQLite → app → run)
Shared Infrastructure (internal/pkg/)
internal/pkg/apierror/
apierror.go - API error wrapper (Code, Message, Err)
internal/pkg/controller/
controller.go - HTTP response helpers (SendSuccess/SendFail/SendError, DecodeAndValidate)
- Custom validators: entity_id (UUID), slug (lowercase alphanum+hyphens)
internal/pkg/middleware/
middleware.go - RequestLogger, RequireAuth (JWT Bearer), LimitBodySize (512KB),
RateLimit (5/s per IP, 10 burst, 10min cleanup)
internal/pkg/websocket/
hub.go - WebSocket hub (max 1000 clients, 64KB read, project-scoped broadcast)
pump.go - Generic write pump
constants.go - WriteWait(10s), PongWait(60s), PingPeriod(54s), MaxMessageSize(4KB)
internal/pkg/sse/
hub.go - Server-Sent Events hub (max 1000 subscribers/project, 1s heartbeat)
internal/agachconfig/
config.go - Client config (.agach.yml), secure YAML loading (perms ≤ 0600)
Public Packages (pkg/)
pkg/server/
types.go - All HTTP request/response structs with validation tags
client/client.go - Go HTTP client SDK (projects, tasks, comments, dependencies, agents)
pkg/daemonws/
types.go - Docker WebSocket message protocol (list, rebuild, logs, prune, events)
chat.go - Chat WebSocket protocol (start, message, end, stats, TTL warning)
pkg/domainerror/
error.go - Domain error type (Code + Message + wrapped error)