Multica Repository Analysis: Key Files Map

Essential Files to Understand the System

Backend -- Server Core

File	Lines	Responsibility
`server/cmd/server/main.go`	142	Server entry point, boot sequence, graceful shutdown
`server/cmd/server/router.go`	478	Full route tree, middleware chain, handler wiring
`server/cmd/server/autopilot_scheduler.go`	~100	Background scheduler for autopilot cron triggers
`server/internal/events/bus.go`	89	In-process synchronous event pub/sub
`server/internal/handler/handler.go`	~68	Handler struct with all dependencies
`server/internal/handler/issue.go`	~400+	Issue CRUD, search, batch operations
`server/internal/handler/chat.go`	~300+	Chat session management, message dispatch
`server/internal/handler/agent.go`	~300+	Agent CRUD, skill binding, task listing
`server/internal/handler/task_lifecycle.go`	~200+	Task claiming, progress, completion, cancellation
`server/internal/handler/autopilot.go`	~200+	Autopilot triggers and run management
`server/internal/middleware/auth.go`	98	JWT/PAT/cookie auth with CSRF for state-changing requests
`server/internal/middleware/daemon_auth.go`	120	Daemon token validation with JWT/PAT fallback
`server/internal/middleware/workspace.go`	216	Workspace resolution and membership enforcement
`server/internal/realtime/hub.go`	~200+	WebSocket connection manager, scoped broadcasts
`server/internal/realtime/redis_relay.go`	~200+	Multi-node fanout via Redis Streams
`server/internal/service/task.go`	77	Task enqueue logic for issues and mentions
`server/internal/service/autopilot.go`	93	Autopilot dispatch (create_issue vs run_only)
`server/pkg/protocol/events.go`	80+	All event type constants

Backend -- Agent System

File	Lines	Responsibility
`server/pkg/agent/agent.go`	158	Unified `Backend` interface, factory, message types
`server/pkg/agent/claude.go`	581	Claude Code CLI integration (stream-json protocol)
`server/pkg/agent/models.go`	815	Model catalogs (static + dynamic discovery)
`server/pkg/redact/redact.go`	98	PII/secret redaction (12 patterns + home dir masking)

Backend -- Daemon

File	Lines	Responsibility
`server/cmd/multica/main.go`	89	CLI entry point, Cobra command tree
`server/internal/daemon/daemon.go`	1500+	Main daemon: lifecycle, task polling, execution
`server/internal/daemon/config.go`	~150	Agent CLI probing, env config, defaults
`server/internal/daemon/prompt.go`	103	Prompt construction for 4 task types
`server/internal/daemon/types.go`	75	Runtime, Task, AgentData, TaskResult types
`server/internal/daemon/execenv/execenv.go`	~150	Isolated work directory creation
`server/internal/daemon/execenv/runtime_config.go`	242	Meta skill content generation (the "brain" of agent context)

Backend -- Database

File	Lines	Responsibility
`server/sqlc.yaml`	12	sqlc code generation config
`server/pkg/db/queries/issue.sql`	-	Issue queries (CRUD, search, batch)
`server/pkg/db/queries/agent.sql`	-	Agent queries, task creation
`server/pkg/db/queries/runtime.sql`	-	Runtime upsert, heartbeat, stale detection
`server/pkg/db/queries/chat.sql`	-	Chat session and message queries
`server/pkg/db/queries/autopilot.sql`	-	Autopilot CRUD and run management
`server/pkg/db/queries/task_usage.sql`	-	Token usage tracking per task
`server/pkg/db/queries/task_message.sql`	-	Per-message storage for task execution

Frontend -- Core Package

File	Lines	Responsibility
`packages/core/platform/core-provider.tsx`	96	Root provider, singleton initialization
`packages/core/platform/workspace-storage.ts`	108	URL-driven workspace singleton, rehydration
`packages/core/platform/storage.ts`	-	SSR-safe localStorage wrapper
`packages/core/api/client.ts`	1062	Full HTTP API client (all endpoints)
`packages/core/api/ws-client.ts`	168	WebSocket client with auto-reconnect
`packages/core/auth/store.ts`	138	Zustand auth store (login/logout flows)
`packages/core/realtime/provider.tsx`	151	WSProvider with auth-gated connection
`packages/core/realtime/use-realtime-sync.ts`	300+	WS event -> React Query cache invalidation
`packages/core/issues/store.ts`	-	Active issue tracking
`packages/core/issues/stores/view-store.ts`	100+	Board/list filters, sort, view mode
`packages/core/issues/queries.ts`	-	React Query keys and options for issues
`packages/core/issues/mutations.ts`	-	Optimistic mutations for issue operations
`packages/core/issues/ws-updaters.ts`	-	WS event handlers for issue events
`packages/core/chat/store.ts`	80+	Chat UI state (session, agent, drafts)
`packages/core/query-client.ts`	-	React Query config (staleTime: Infinity)
`packages/core/types/events.ts`	150+	60+ WS event types and payload interfaces
`packages/core/navigation/store.ts`	50	Last-visited path persistence

Frontend -- Views Package

File	Lines	Responsibility
`packages/views/layout/dashboard-layout.tsx`	44	Root dashboard shell (sidebar + content)
`packages/views/layout/app-sidebar.tsx`	80+	Navigation sidebar with workspace switcher
`packages/views/layout/dashboard-guard.tsx`	-	Auth check before rendering
`packages/views/issues/components/issues-page.tsx`	-	Main issues container
`packages/views/issues/components/board-view.tsx`	-	Kanban board
`packages/views/issues/components/list-view.tsx`	-	Table/list view
`packages/views/issues/components/issue-detail.tsx`	-	Full issue modal
`packages/views/chat/chat-page.tsx`	-	Chat interface with agents
`packages/views/editor/content-editor.tsx`	-	TipTap rich text editor
`packages/views/modals/`	-	Registry-based modal system

Frontend -- Web App

File	Lines	Responsibility
`apps/web/app/layout.tsx`	123	Root layout (fonts, metadata, providers)
`apps/web/app/[workspaceSlug]/layout.tsx`	92	Workspace resolution, auth guard
`apps/web/components/web-providers.tsx`	70	CoreProvider config (cookie auth, WS URL)
`apps/web/platform/navigation.tsx`	40	Next.js router -> NavigationAdapter bridge
`apps/web/middleware.ts`	-	Edge middleware for auth redirects

Frontend -- Desktop App

File	Lines	Responsibility
`apps/desktop/src/main/index.ts`	200+	Electron main process, deep linking, daemon
`apps/desktop/src/renderer/src/App.tsx`	228	Renderer root, daemon sync, workspace validation
`apps/desktop/src/renderer/src/platform/navigation.tsx`	249	Two-tier navigation (root + per-tab), overlay interception
`apps/desktop/src/renderer/src/stores/tab-store.ts`	-	Multi-workspace tab management

Configuration

File	Lines	Responsibility
`CLAUDE.md`	~500	Comprehensive AI coding assistant guidance
`pnpm-workspace.yaml`	-	Workspace pattern + dependency catalog
`turbo.json`	-	Build pipeline, task dependencies, env vars
`.env.example`	131	All configuration variables documented
`Makefile`	311	One-command dev, setup, build, deploy
`docker-compose.selfhost.yml`	-	Production self-hosting config
`.github/workflows/ci.yml`	-	Frontend + backend CI pipeline
`.goreleaser.yml`	-	Cross-platform CLI release config

Important Prompts & Agent Instructions

The most strategically important file for understanding how agents work is the meta skill content generated at runtime:

`server/internal/daemon/execenv/runtime_config.go:41-242`

This is the "brain" of every agent execution. The buildMetaSkillContent function generates the CLAUDE.md/AGENTS.md/GEMINI.md that teaches agents about their environment. It includes:

Agent Identity (:49-66) -- name, ID, custom instructions
Available CLI Commands (:68-96) -- full multica CLI reference
Repository Checkout (:99-113) -- available repos and how to check them out
Workflow Mode (:116-176) -- different instructions for:
- Chat tasks (:117-126)
- Autopilot run-only tasks (:127-153)
- Comment-triggered tasks (:154-165)
- Assignment-triggered tasks (:166-176)
Skills Reference (:178-198) -- list of installed skills
Mention System (:200-213) -- rules for @mentioning (with loop prevention)
Attachment Handling (:216-221) -- how to download and use files
CLI-Only Rule (:223-228) -- never use curl/wget for Multica URLs
Output Requirements (:230-239) -- results MUST be posted as comments

`server/internal/daemon/prompt.go:1-103`

Task-specific prompts for the 4 execution modes:

Default (assignment): "Your assigned issue ID is: X. Start by running multica issue get X..." (:23-27)
Comment-triggered: Embeds triggering comment content, warns about agent-to-agent loop prevention (:36-58)
Chat: "A user is chatting with you directly. Respond to their message." (:61-67)
Autopilot: Autopilot description + instructions, no issue context (:70-103)

Custom agent instructions (set in the UI) are injected into the meta skill content under "## Agent Identity". This is how workspace owners customize agent behavior without modifying the platform code.