---
name: mosaic-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   | 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

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