---
name: jarvis
description: "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`:

```python
# 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:

```python
# 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:

```python
@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:

```tsx
// 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
```bash
cd apps/api
alembic revision --autogenerate -m "description"
alembic upgrade head
```

---

## Testing

### Backend
```bash
cd apps/api
pytest
pytest --cov=src
```

### Frontend
```bash
cd apps/web
npm test
npm run test:e2e
```

---

## Quality Commands

```bash
# 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 | Ralph autonomous coding 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

```bash
# 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`