This document breaks down the main repository structure so contributors can find the backend runtime, dashboard, shared contracts, and operational docs quickly.
openhive/
├── server/
│ ├── hive/
│ │ ├── main.py # FastAPI entry point (uvicorn hive.main:app)
│ │ ├── config.py # Pydantic Settings
│ │ ├── errors.py # Typed exception hierarchy
│ │ ├── agent/ # Unified agent runtime
│ │ │ ├── runtime.py # HiveAgent — single agent loop
│ │ │ ├── config.py # AgentConfig + factory functions
│ │ │ ├── ai_settings.py # Managed agent conversation-model resolution
│ │ │ ├── memory.py # Layered memory with LLM compaction
│ │ │ ├── context.py # Context window manager
│ │ │ ├── llm.py # LLMClient
│ │ │ ├── providers/ # Anthropic + OpenAI-compatible providers
│ │ │ └── tools/ # ToolRegistry + Keeper/Scout tools
│ │ ├── gateway/ # Platform gateway (LLM-free)
│ │ │ ├── feishu.py # FeishuClient (lark-oapi SDK) — send text + cards
│ │ │ ├── feishu_ws.py # WebSocket long-connection event dispatcher
│ │ │ ├── feishu_cards.py # Gateway-owned interactive card builders (approval/control-plane)
│ │ │ ├── card_handlers.py # Card button action handlers
│ │ │ ├── password.py # scrypt password hashing + verification
│ │ │ ├── middleware.py # Dashboard session token encode/decode + FastAPI dependency
│ │ │ ├── router.py # Message routing
│ │ │ ├── bot.py # GatewayBot (admission + navigation, no LLM)
│ │ │ ├── auth.py # AuthChecker (whitelist + invite codes)
│ │ │ ├── scheduler.py # Config-driven cron scheduler
│ │ │ ├── template_service.py # load_templates / apply_template
│ │ │ ├── project_service.py # create_project (shared by bot + API)
│ │ │ ├── credential_proxy.py
│ │ │ └── api/ # Dashboard REST API
│ │ │ ├── projects.py # /api/projects + /api/templates (public)
│ │ │ ├── admin.py # GET/POST /api/admin/users, invite-codes
│ │ │ └── auth.py # POST /api/auth/login, GET /api/auth/me, POST /api/auth/logout
│ │ ├── pool/ # Agent lifecycle management
│ │ ├── plugins/ # Business-specific extensions
│ │ │ └── notification/ # Channel-specific notification plugins
│ │ │ ├── feishu.py # PM/group notification delivery via Feishu
│ │ │ ├── card_actions.py # Neutral plugin card-action dispatcher
│ │ ├── skills/ # Skill execution engine
│ │ ├── pipelines/ # Pipeline engine
│ │ ├── security/ # Content wrapping + credential resolution
│ │ └── db/ # ScopedDB + SQLAlchemy models + Alembic
│ ├── templates/ # Project templates (YAML, one per use-case)
│ │ └── starter-workspace.yaml
│ ├── skills/ # Skill library (subprocess scripts)
│ │ ├── core/ # pre-processor, router, post-processor
│ │ ├── classifiers/ # shared classifier skills
│ │ ├── detectors/ # reserved for project-local detector imports; public repo ships no vertical examples
│ │ ├── handlers/ # shared handler skills
│ │ └── pipeline-skills/ # reserved for project-local pipeline imports; public repo ships no vertical examples
│ ├── runtime-seeds/ # Versioned runtime seeds and templates copied into the mutable workspace
│ └── tests/ # Backend tests (pytest + pytest-asyncio)
├── .runtime/ # Generated local runtime workspace (`projects/`, `extensions/`), ignored by Git
├── web/
│ └── src/
│ ├── app/
│ │ ├── login/ # Username/password login page
│ │ ├── projects/ # Project overview, detail, sessions, usage
│ │ ├── usage/ # Cross-project account usage views
│ │ ├── audit/ # Audit log page with diff viewer and filters
│ │ └── admin/ # User + invite code management
│ ├── components/
│ │ ├── navbar.tsx # Client navbar with user menu + logout
│ │ ├── conversation-transcript.tsx # Session transcript viewer
│ │ ├── trace-detail.tsx # Prompt / tool / usage detail viewer
│ │ ├── project-card.tsx # Project summary card
│ │ ├── agent-status.tsx # Agent status badge + card
│ │ ├── trend-chart.tsx # ECharts line chart + range selector
│ │ ├── change-diff.tsx # Expandable inline diff viewer
│ │ └── pagination.tsx # Reusable pagination component
│ ├── lib/
│ │ ├── api.ts # Typed API client (projectsApi, adminApi, authApi)
│ │ ├── auth-context.tsx # AuthProvider + useAuth() hook
│ │ └── providers.tsx # TanStack QueryClientProvider + AuthProvider
│ ├── middleware.ts # Next.js middleware (auth redirect)
│ └── types/
│ └── api.ts # TypeScript API types (synced with packages/shared/)
├── packages/
│ └── shared/
│ ├── api_types.py # Pydantic models — source of truth for API contract
│ └── api_types.ts # Generated TypeScript contract mirror
├── docs/
│ ├── contribution-workflow.md # Branches, PR titles, and commit conventions
│ ├── getting-started.md # Full setup guide with troubleshooting
│ ├── hotfix-sop.md # Step-by-step commands for shipped-version bug fixes
│ ├── project-layout.md # This file
│ ├── operations.md # Backup, restore, process, and health operations
│ ├── release-workflow.md # Maintenance branches, hotfixes, and forward/backports
│ └── e2e-test-checklist.md # Manual end-to-end pipeline checklist
├── docker-compose.yml
├── Dockerfile.gateway
├── Makefile
└── .env.example
- Start in
server/hive/if you are changing runtime, gateway, DB, or agent logic. - Start in
web/src/app/if you are changing dashboard pages or flows. - Check
packages/shared/first before changing API contracts. - Use
docs/for public documentation and contributor-facing contracts. - Use the private companion docs repo only when maintainer work needs unpublished planning or KB context.
- See
docs/ARCHITECTURE.mdfor the supported public memory contract before changing runtime project files or related docs. - For source-based local development, mutable runtime state lives under
.runtime/; versioned bootstrap content lives underserver/runtime-seeds/.