Multica Repository Analysis: Entry Points & Execution Flow

Server Entry Points

1. API Server -- `server/cmd/server/main.go:21`

The primary backend process. Starts HTTP server + WebSocket hub + background workers.

Boot sequence (line-by-line):

logger.Init() -- structured slog with tint colorization (:22)
JWT_SECRET / RESEND_API_KEY warnings (:25-29)
newDBPool(ctx, dbURL) -- pgxpool connection to PostgreSQL (:44)
events.New() -- in-process event bus (:58)
realtime.NewHub() + hub.Run() -- WebSocket connection manager (:59-60)
Redis relay setup (optional, :71-84)
registerListeners(bus, broadcaster) -- wire events -> WS broadcasts (:85)
analytics.NewFromEnv() -- PostHog client (:87)
registerSubscriberListeners, registerActivityListeners, registerNotificationListeners (:95-97) -- order matters: subscribers before notifications
NewRouter(pool, hub, bus, analyticsClient, rdb) -- full Chi router (:99)
Background workers: runRuntimeSweeper, runAutopilotScheduler, runDBStatsLogger (:114-116)
srv.ListenAndServe() on configurable port (:121)
Graceful shutdown on SIGINT/SIGTERM with 10s timeout (:127-141)

2. CLI + Daemon -- `server/cmd/multica/main.go:1-89`

Cobra-based CLI that doubles as the daemon process.

Command tree (:36-88):

multica
├── login          # Authenticate with server
├── setup          # Interactive workspace setup
├── auth           # Auth management
├── daemon         # Start/stop local agent daemon
│   ├── start      # Start daemon (foreground or background)
│   └── stop       # Stop running daemon
├── issue          # Issue CRUD
│   ├── get        # Get issue details
│   ├── list       # List issues with filters
│   ├── create     # Create new issue
│   ├── update     # Update issue fields
│   ├── status     # Change issue status
│   ├── assign     # Assign to member/agent
│   ├── comment    # Comment subcommands
│   │   ├── add    # Add comment
│   │   ├── list   # List comments
│   │   └── delete # Delete comment
│   ├── runs       # List task runs
│   └── run-messages # List messages for a run
├── project        # Project CRUD
├── agent          # Agent management
├── autopilot      # Autopilot CRUD + trigger
├── workspace      # Workspace info
├── repo           # Repository checkout
├── skill          # Skill management
├── runtime        # Runtime listing
├── attachment     # Attachment download
├── config         # CLI configuration
├── update         # Self-update
└── version        # Version info

Daemon lifecycle (daemon/daemon.go:92-139):

listenHealth() -- bind health port (detect duplicate daemon)
Resolve auth via token or multica login
probeAndRegisterRuntimes() -- scan PATH for agent CLIs
Start workspace sync loop
Start heartbeat loop
Start GC (garbage collection) loop
pollForTasks() -- main polling loop

3. Migration Runner -- `server/cmd/migrate/main.go:14-119`

Standalone binary for schema migrations.

Tracks applied versions in schema_migrations table
Bidirectional (up/down)
Idempotent: skips already-applied migrations
Used by docker/entrypoint.sh before server start

Frontend Entry Points

4. Web App -- `apps/web/app/layout.tsx`

Next.js App Router root layout.

Provider chain:

<ThemeProvider>
  <WebProviders>        -- apps/web/components/web-providers.tsx
    <CoreProvider>      -- packages/core/platform/core-provider.tsx
      <QueryProvider>   -- TanStack React Query
        <AuthInitializer>
          <WSProvider>  -- WebSocket connection
            {children}  -- App Router pages
          </WSProvider>
        </AuthInitializer>
      </QueryProvider>
    </CoreProvider>
  </WebProviders>
</ThemeProvider>

Routing structure (apps/web/app/):

app/
├── (landing)/          # Public pages (home, about, changelog, download)
├── (auth)/
│   ├── login/          # Email/Google login
│   └── onboarding/     # First-time setup
├── auth/callback/      # Google OAuth redirect
├── [workspaceSlug]/    # Workspace-scoped routes
│   └── (dashboard)/
│       ├── issues/     # Issue board/list
│       ├── chat/       # Agent chat
│       ├── projects/   # Project management
│       ├── inbox/      # Notification inbox
│       ├── search/     # Global search
│       ├── runtimes/   # Runtime management
│       ├── agents/     # Agent configuration
│       ├── autopilots/ # Autopilot management
│       └── settings/   # Workspace settings
├── workspaces/new/     # Create workspace
└── invite/[id]/        # Accept invitation

Workspace resolution flow (app/[workspaceSlug]/layout.tsx):

Auth guard: redirect to /login if not authenticated (:30-32)
Resolve workspace by slug from React Query cache (:36-39)
setCurrentWorkspace(slug, wsId) -- sync platform singleton (:46)
Write last_workspace_slug cookie (:52-56)
Validate access -- show NoAccessPage if forbidden (:83)
Wrap in WorkspaceSlugProvider (:87)

5. Desktop App -- `apps/desktop/src/main/index.ts`

Electron main process.

Key responsibilities:

Deep linking: multica://auth/callback?token=<jwt> and multica://invite/<id>
Window management: 1280x800 min, hiddenInset titlebar
Daemon manager: spawns child process for local agent execution
WS origin stripping: removes Origin header from WS upgrade for dev localhost
Auto-updater integration
CLI bootstrap: ensures shell PATH is available for agent binaries

Renderer entry: src/renderer/src/App.tsx:1-228

Same provider chain as web, but with desktop-specific additions:

setTargetApiUrl() / syncToken() / autoStart() for daemon management
Deep-link handlers for invite and auth
Tab-based routing (multi-tab per workspace)
Window overlay system (instead of route-based modals)

Key State Transitions

Issue Lifecycle

                create
                  |
                  v
    +----------> todo
    |             |
    |    assign   |  start work
    |             v
    |        in_progress
    |         /       \
    |   block /         \ submit
    |       v             v
    |    blocked      in_review
    |       |             |
    |  unblock|      approve|
    |       v             v
    +------+            done

Agent Task Lifecycle

    create (issue assigned / comment trigger / autopilot / chat)
                  |
                  v
              queued
                  |
         daemon claims
                  v
              running ----timeout----> failed
              /     \
         complete   error
            |         |
            v         v
        completed   failed

Daemon Runtime States

    probe CLI on PATH
           |
           v
       detected ---register---> online
                                  |
                          heartbeat loop
                             /        \
                     heartbeat OK    missed heartbeats
                         |                |
                         v                v
                      online          stale --> offline
                                        |
                                  orphaned tasks
                                  reassigned/failed

WebSocket Connection Lifecycle

    app mounts WSProvider
           |
    check auth token + workspace slug
           |
           v
    connect to /ws?token=...&slug=...
           |
           v
       connected ----message----> useRealtimeSync
           |                        |
    disconnected                 invalidate
    (3s delay)                   React Query
           |                     cache
           v
      reconnect

Request Flow Through Middleware

A workspace-scoped API request (e.g., POST /api/issues) passes through:

Request
  |
  v
1. chimw.RequestID      -- assigns X-Request-ID
  |
  v
2. middleware.ClientMetadata  -- extracts X-Client-Platform/Version/OS
  |
  v
3. middleware.RequestLogger   -- structured slog (method, path, status, duration)
  |
  v
4. chimw.Recoverer     -- panic recovery
  |
  v
5. middleware.CSP       -- Content-Security-Policy headers
  |
  v
6. cors.Handler         -- CORS validation (configurable origins)
  |
  v
7. middleware.Auth      -- JWT (cookie or header) or PAT validation
  |                       sets X-User-ID, X-User-Email in context
  v
8. middleware.RequireWorkspaceMember  -- resolves workspace, validates membership
  |                                    injects workspace ID into context
  v
9. handler.CreateIssue  -- business logic
  |
  v
10. bus.Publish         -- event dispatch
  |
  v
11. Event listeners     -- subscribers, activity, notifications, realtime broadcast

Background Workers

Worker	Interval	Purpose	File
Runtime Sweeper	Periodic	Mark stale runtimes offline, fail orphaned tasks	`server/cmd/server/main.go:114`
Autopilot Scheduler	30s	Poll due schedule triggers, dispatch autopilot runs	`server/cmd/server/autopilot_scheduler.go`
DB Stats Logger	Periodic	Log connection pool statistics	`server/cmd/server/main.go:116`
Daemon Heartbeat	Configurable	Keep runtimes marked online	`daemon/daemon.go:135`
Daemon GC	Configurable	Clean old work directories (24h TTL, 72h orphan)	`daemon/daemon.go:136`
Daemon Task Poller	Continuous	Poll for and claim pending tasks	`daemon/daemon.go:138`