Architecture Overview

Core Idea

JARVIS is a local-first orchestration layer for repository-aware coding workflows. It accepts human instructions, resolves context, chooses the right workflow path, and delegates execution to specialized agents and services.

Runtime Layers

Presentation

The current primary transport is Telegram.

• src/jarvis/presentation/telegram/ renders outbound messages and callback UI.
• src/jarvis/services/telegram_bridge.py handles inbound polling and outbound Telegram API calls.
• src/jarvis/main.py wires transport to orchestration.

Orchestration

src/jarvis/agents/orchestrator.py is the runtime hub.

It creates the agent graph, initializes stores and managers, resolves policy, routes incoming instructions, and coordinates the use cases that answer each request.

Application Layer

The application layer turns routed intent into explicit workflows.

• src/jarvis/app/routing/ normalizes and routes requests
• src/jarvis/app/use_cases/ contains command-oriented workflows such as repo activation, status, and code change approval
• src/jarvis/app/context/ resolves what memory and repo context should be included for each decision

Agents

The specialized agents separate responsibilities:

• PlannerAgent prepares model-driven planning behavior
• RepoAgent handles repository-oriented understanding
• CodeAgent proposes and applies workspace changes
• VerificationAgent runs checks and test commands
• GitAgent handles branch and git-oriented operations

Services and Persistence

Service objects encapsulate integrations and storage concerns.

• Workspace and repo inspection live under src/jarvis/services/
• Persistent state is stored through dedicated managers and stores for sessions, repo profiles, episodes, and pending changes
• Runtime configuration comes from src/jarvis/settings.py

Architectural Boundaries

The codebase is trending toward these boundaries:

• transport stays outside business logic
• routing decides what should happen, not how tools execute
• use cases orchestrate workflows with explicit dependencies
• services isolate persistence and external integrations
• agents focus on role-specific decision and execution behavior