stack/skills/mosaic-jarvis/SKILL.md

name, description

name	description
mosaic-jarvis	Jarvis Platform development context. Use when working on the jetrich/jarvis repository. Provides architecture knowledge, coding patterns, and component locations.

Jarvis Platform Development

Project Overview

Jarvis is a self-hosted AI assistant platform built with:

• Backend: FastAPI (Python 3.11+)
• Frontend: Next.js 14+ (App Router)
• Database: PostgreSQL with pgvector
• Plugins: Modular LLM providers and integrations

Repository: jetrich/jarvis

---

Architecture

jarvis/
├── apps/
│   ├── api/                 # FastAPI backend
│   │   └── src/
│   │       ├── routes/      # API endpoints
│   │       ├── services/    # Business logic
│   │       ├── models/      # SQLAlchemy models
│   │       └── core/        # Config, deps, security
│   └── web/                 # Next.js frontend
│       └── src/
│           ├── app/         # App router pages
│           ├── components/  # React components
│           └── lib/         # Utilities
├── packages/
│   └── plugins/             # jarvis_plugins package
│       └── jarvis_plugins/
│           ├── llm/         # LLM providers (ollama, claude, etc.)
│           └── integrations/# External integrations
├── docs/
│   └── scratchpads/         # Agent working docs
└── scripts/                 # Utility scripts

---

Key Patterns

LLM Provider Pattern

All LLM providers implement BaseLLMProvider:

# packages/plugins/jarvis_plugins/llm/base.py
class BaseLLMProvider(ABC):
    @abstractmethod
    async def generate(self, prompt: str, **kwargs) -> str: ...

    @abstractmethod
    async def stream(self, prompt: str, **kwargs) -> AsyncIterator[str]: ...

Integration Pattern

External integrations (GitHub, Calendar, etc.) follow:

# packages/plugins/jarvis_plugins/integrations/base.py
class BaseIntegration(ABC):
    @abstractmethod
    async def authenticate(self, credentials: dict) -> bool: ...

    @abstractmethod
    async def execute(self, action: str, params: dict) -> dict: ...

API Route Pattern

FastAPI routes use dependency injection:

@router.get("/items")
async def list_items(
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
    service: ItemService = Depends(get_item_service)
):
    return await service.list(db, current_user.id)

Frontend Component Pattern

Use shadcn/ui + server components by default:

// Server component (default)
export default async function DashboardPage() {
  const data = await fetchData();
  return <Dashboard data={data} />;
}

// Client component (when needed)
('use client');
export function InteractiveWidget() {
  const [state, setState] = useState();
  // ...
}

---

Database

• ORM: SQLAlchemy 2.0+
• Migrations: Alembic
• Vector Store: pgvector extension

Creating Migrations

cd apps/api
alembic revision --autogenerate -m "description"
alembic upgrade head

---

Testing

Backend

cd apps/api
pytest
pytest --cov=src

Frontend

cd apps/web
npm test
npm run test:e2e

---

Quality Commands

# Backend
cd apps/api
ruff check .
ruff format .
mypy src/

# Frontend
cd apps/web
npm run lint
npm run typecheck
npm run format

---

Active Development Areas

Issue	Feature	Priority
#84	Per-function LLM routing	High
#85	Embedded E2E autonomous delivery loop	High
#86	Thinking models (CoT UI)	Medium
#87	Local image generation	Medium
#88	Deep research mode	Medium
#89	Uncensored models + alignment	Medium
#90	OCR capabilities	Medium
#91	Authentik SSO	Medium
#40	Claude Max + Claude Code	High

---

Environment Setup

# Backend
cd apps/api
cp .env.example .env
pip install -e ".[dev]"

# Frontend
cd apps/web
cp .env.example .env.local
npm install

# Database
docker-compose up -d postgres
alembic upgrade head

---

Commit Convention

<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123

Types: feat, fix, docs, test, refactor, chore