Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.11+ - Required for the FastAPI backend
  • Node.js 20+ - Required for the Next.js frontend
  • uv - Fast Python package installer (recommended)
  • Git - For version control

​
Project Structure

jarvis/
├── backend/                    # Python FastAPI service
│   ├── main.py                # FastAPI app entry point
│   ├── config.py              # Environment configuration
│   ├── pipeline.py            # Core capture pipeline
│   ├── agents/                # Browser Use agent swarm
│   ├── capture/               # Photo capture & frame extraction
│   ├── identification/        # Face detection & recognition
│   ├── synthesis/             # Report generation
│   ├── enrichment/            # API-based enrichment (Exa)
│   ├── db/                    # Database clients
│   ├── observability/         # Laminar tracing
│   └── tests/                 # Test suite
│
├── frontend/                   # Next.js application
│   ├── app/                   # Next.js app router
│   ├── components/            # React components
│   ├── convex/                # Convex real-time database
│   └── lib/                   # Utilities
│
└── docs/                      # This documentation site

​
Backend Setup

1

Clone the repository

git clone <repository-url>
cd jarvis/backend
2

Install Python dependencies

Using uv (recommended):
uv pip install -e ".[dev]"
Or using pip:
pip install -e ".[dev]"
3

Configure environment variables

Copy the example environment file:
cp .env.example .env
Edit .env with your API keys and configuration. See Configuration for details.
4

Start the development server

uvicorn main:app --reload --port 8000
The API will be available at http://localhost:8000

​
Frontend Setup

1

Navigate to frontend directory

cd ../frontend
2

Install Node.js dependencies

npm install
3

Configure environment variables

Copy the example environment file:
cp .env.example .env.local
Set your Convex URL and other frontend configuration.
4

Start the development server

npm run dev
The application will be available at http://localhost:3000

​
Verify Installation

​
Check Backend Health

curl http://localhost:8000/health
Expected response: 
{
  "status": "ok",
  "service": "jarvis",
  "services": {
    "convex": false,
    "mongodb": false,
    "exa": false,
    "browser_use": false,
    "openai": false,
    "gemini": false,
    "laminar": false
  }
}
Service flags will show true once you’ve configured the corresponding API keys.

​
Run Backend Tests

cd backend
pytest

​
Access API Documentation

FastAPI provides interactive API documentation at:

​
Development Tools

​
Code Quality

The project uses Ruff for linting and formatting: 
# Check code style
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

​
Type Checking

Python code uses Pydantic for runtime validation. The project targets Python 3.11+.

​
Hot Reload

Both backend and frontend support hot reload:
  • Backend: uvicorn --reload flag watches for Python file changes
  • Frontend: Next.js dev server watches for TypeScript/React changes

​
Common Issues

​
Port Already in Use

If port 8000 or 3000 is already in use: 
# Backend - use different port
uvicorn main:app --reload --port 8001

# Frontend - use different port
PORT=3001 npm run dev

​
Module Import Errors

Ensure you’re running commands from the correct directory:
  • Backend commands should run from backend/
  • Frontend commands should run from frontend/

​
Missing Dependencies

If you encounter missing dependencies: 
# Backend
uv pip install -e ".[dev]"

# Frontend
rm -rf node_modules package-lock.json
npm install

​
Development Workflow

  1. Create a feature branch 
    git checkout -b feature/your-feature-name
  2. Make your changes with hot reload active
  3. Run tests before committing 
    pytest  # Backend tests
  4. Commit your changes 
    git add .
git commit -m "feat: your feature description"
  5. Push and create a pull request 
    git push origin feature/your-feature-name

​
Next Steps

Configuration

Learn about environment variables and service configuration

Testing

Write and run tests for your code

Architecture

Understand the system architecture

Contributing

Guidelines for contributing to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us