207 lines
4.2 KiB
Markdown
207 lines
4.2 KiB
Markdown
---
|
|
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`
|