Job Copilot is a full-stack productivity assistant for job seekers. It connects to Gmail and Google Calendar via Supabase Auth, keeps an always-on sync of messages, classifies every incoming email with a local Ollama model, and surfaces the current state of each application in a React dashboard.

For deeper architectural notes see docs/ARCHITECTURE.md.

Create secure values for the Rails Active Record encryption keys (each must be 32-byte Base64 strings) and store every secret using your preferred secret manager. The tables below list the minimum environment variables required.

VITE_API_URL=http://localhost:3000
VITE_SUPABASE_URL=https://<your-project>.supabase.co
VITE_SUPABASE_ANON_KEY=<anon-key>
VITE_GOOGLE_CLIENT_ID=<oauth-client-id>

The Google OAuth client must include http://localhost:5173 (dev) and your deployed Vercel domains as authorized redirect URIs.

Refer to agent/README.md for the full list of optional toggles.

# Start Redis
redis-server

# Start Ollama (model download may take time)
ollama run llama3.1

Ensure your Supabase project has Gmail + Calendar APIs enabled and that the redirect URIs match the environment variables above.

cd backend
bundle install

# Apply database schema to Supabase (runs migrations against DATABASE_URL)
bundle exec rails db:migrate

# Run the Rails server on http://localhost:3000
bundle exec rails server

# In a second terminal, run Sidekiq
bundle exec sidekiq

Key dev endpoints (all under http://localhost:3000/api/v1):

• GET /messages – list messages for the authenticated Supabase user
• PATCH /messages/:id/claim – mark a message as triage-in-progress
• PATCH /messages/:id – update classification + metadata
• POST /sync/gmail – enqueue a Gmail sync job

cd agent
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

# With backend + Ollama running
inbox-triage-agent

The agent polls the API for messages classified as other, optionally claims them, and writes back the LLM or rule-based result.

cd frontend
npm install
npm run dev

Visit http://localhost:5173 and complete the Supabase Google sign-in. Once authenticated, you can trigger manual syncs, review classifications, and manage application statuses.

Run focused suites before committing:

• Backend

   cd backend
   bundle exec rails test
   bundle exec ruby -Itest test/controllers/messages_controller_test.rb
   bundle exec ruby -Itest test/controllers/classifications_controller_test.rb
   bundle exec ruby -Itest test/services/email_classifier_test.rb

• Inbox agent

   cd agent
   source .venv/bin/activate
   python -m pytest

• Frontend

   cd frontend
   npm run lint
   npm run build

1. Deploy the Rails API + Sidekiq worker to a host that supports Ruby (Render, Fly.io, Heroku). Provide Supabase, Redis, Google, and encryption secrets. Run rails db:migrate on release.
2. Deploy the inbox triage agent as a long-lived worker (Render background worker, Fly.io machine, etc.) with access to the API, Redis/Ollama, and the same secrets.
3. Deploy the Vite frontend to Vercel. Set VITE_* environment variables in the Vercel dashboard and add the production domain to Google OAuth.
4. Update DNS (optional) and monitor Supabase, Sidekiq, and agent logs for initial traffic.

For a fuller deployment checklist, see the guidance in the project history or adapt the steps above to your target platform.

• docs/ARCHITECTURE.md
• docs/ENDPOINTS.md
• agent/README.md
• backend/README.md (fill in platform specifics for your environment)

Happy shipping!