arcai-hr

A reusable API/action foundation for ArcAI vertical applications, proved out with HR as the first vertical.

Architecture

        UI Layer (React + Tailwind, GrowthArc tokens)
              |  calls
        MCP Layer -- FastMCP / ARC MCP
              |  exports the same catalog as
        HR Vertical Layer -- services + ARC Actions
              |  built on
        Base/API Layer -- reusable FastAPI core

• Base layer (app/core, app/db, app/actions, app/mcp): config, DB plumbing, identity/ActionContext, error mapping, and a generic route generator that mounts one FastAPI endpoint per arcai_core.ArcAction in any ActionCatalog -- vertical-agnostic.

• HR vertical layer (app/verticals/hr, added in Phase 2): models, services, and real ArcActions built on arcai_core.

• MCP layer: the same catalog exported as FastMCP tools via the generic exporter in app/mcp.

• UI layer: a minimal React + TypeScript + Tailwind app (Phase 4), following docs/GrowthArc-UIUX-Design-System-Guidelines.md.

arcai-runtime (auth, approvals, SSE, audit) is explicitly out of scope for this round -- the pieces above are small, dependency-free implementations of the same pattern, built from scratch to learn it.

Related MCP server: Homerun ATS MCP Server

Setup

This project depends on arcai-core as an editable sibling checkout. Clone it next to this repo:

Projects/
  arcai-core/
  arcai-hr/

Then, from this directory:

uv sync

Run

uv run uvicorn main:app --reload

main.py creates the HR tables (SQLite, zero setup) and mounts the HR action catalog. Interactive docs at http://localhost:8000/docs; the catalog manifest at GET /actions.

Demo data (4 openings, 9 candidates across every stage, interviews, feedback):

uv run python seed.py

Safe to re-run; delete arcai_hr.db to start from scratch.

MCP

The same catalog, exported as MCP tools over stdio (one tool per action, flat arguments from each action's input model, read_only -> readOnlyHint):

uv run python mcp_server.py

UI

React + TypeScript + Tailwind v4 (+ Radix Dialog, Lucide), styled from the GrowthArc tokens in ui/src/index.css. Talks to the FastAPI layer at VITE_API_URL (default http://localhost:8000).

cd ui
npm install
npm run dev        # http://localhost:5173 -- run the API alongside it

Test

uv run pytest