Jarvis Contractor Assistant

A complete voice-first AI assistant system for contractors across multiple trades. This monorepo contains both the backend API and the React dashboard.

📦 Project Structure

jarvis/
├── backend/              # Node.js Express backend API
│   ├── src/
│   │   ├── db/          # Database schema and connection
│   │   ├── routes/      # API endpoints
│   │   ├── services/    # Business logic (pricing, email, agent)
│   │   ├── types/       # TypeScript type definitions
│   │   └── index.ts     # Express server entry point
│   ├── package.json
│   ├── README.md
│   ├── API.md           # API documentation
│   └── DEPLOYMENT.md    # Deployment guide
│
├── dashboard/           # React TypeScript frontend
│   ├── src/
│   │   ├── api/         # Backend API client
│   │   ├── components/  # React components
│   │   ├── store/       # Zustand state management
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   └── README.md
│
├── README.md            # This file
├── .gitignore
└── docker-compose.yml   # (Optional) Local development setup

🚀 Quick Start

Backend Setup

cd backend
npm install
npm run dev

Backend runs on http://localhost:3000

Dashboard Setup

cd dashboard
npm install
npm run dev

Dashboard runs on http://localhost:5173

🎯 Features

Backend API

• Trade-Agnostic Architecture — Works with any contractor type (gutters, roofing, plumbing, electrical, HVAC, etc.)
• Job Management — Create, update, and track jobs with measurements and materials
• Configurable Pricing Engine — Support for per-unit, tiered, labor-based, and hybrid pricing models
• Quote Generation — Automatically calculate and generate professional quotes
• Email Delivery — Send quotes and updates via email with HTML formatting
• Voice Command Processing — Extract intent and entities from natural language
• Memory & Context — Store contractor profiles and job history with pgvector support
• 38 Passing Tests — Comprehensive test coverage for pricing, voice extraction, and agent logic

Frontend Dashboard

• Job Management — Create, view, and manage jobs with client details
• Quote Generation & Tracking — Generate quotes and track email delivery status
• Professional UI — Modern gradient design with responsive layout
• Real-time Updates — Live status updates for jobs and quotes
• Contractor Settings — Manage profile and communication preferences
• Email Integration — Send quotes directly to clients with delivery tracking

🛠 Tech Stack

Backend

• Runtime: Node.js 22+
• Framework: Express 4
• Database: PostgreSQL + pgvector
• Language: TypeScript
• Testing: Vitest
• Email: Nodemailer
• Voice: OpenAI Realtime API (integration ready)

Frontend

• Framework: React 19
• Language: TypeScript
• Build Tool: Vite
• State Management: Zustand
• HTTP Client: Axios
• Styling: CSS3

📖 Documentation

• Backend API: See backend/API.md for full API documentation
• Backend Setup: See backend/README.md for backend-specific instructions
• Dashboard: See dashboard/README.md for frontend-specific instructions
• Architecture: See backend/ARCHITECTURE.md for system design details
• Deployment: See backend/DEPLOYMENT.md for deployment instructions

🔧 Environment Variables

Backend

Create .env in the backend/ directory:

DATABASE_URL=postgresql://user:password@localhost:5432/jarvis_db
NODE_ENV=development
PORT=3000
OPENAI_API_KEY=sk-...
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
JWT_SECRET=your-secret-key-here

Frontend

Create .env in the dashboard/ directory:

REACT_APP_API_URL=http://localhost:3000/api

📊 API Endpoints

Contractors

• POST /api/contractors — Create contractor
• GET /api/contractors/:id — Get contractor
• GET /api/contractors — List contractors
• PUT /api/contractors/:id — Update contractor
• DELETE /api/contractors/:id — Delete contractor

Jobs

• POST /api/jobs — Create job
• GET /api/jobs/:id — Get job
• GET /api/jobs — List jobs
• PUT /api/jobs/:id — Update job
• DELETE /api/jobs/:id — Delete job

Quotes

• POST /api/quotes — Generate quote
• GET /api/quotes/:id — Get quote
• GET /api/quotes — List quotes
• POST /api/quotes/:id/send — Send quote via email

Voice Processing

• POST /api/voice/extract — Extract intent and entities from text
• POST /api/agent/command — Process voice command

🧪 Testing

Backend Tests

cd backend
npm run test:run

Runs 50+ tests covering:

• Pricing engine calculations
• Voice intent extraction
• Quote generation
• Email formatting
• Agent logic

🚢 Deployment

Docker

docker-compose up

Production Build

Backend:

cd backend
npm run build
npm start

Dashboard:

cd dashboard
npm run build
npm run preview

Cloud Deployment

• Vercel: Deploy dashboard to Vercel, backend to Railway/Render
• Heroku: Use Procfile for backend, dashboard on Vercel
• AWS: ECS for backend, S3 + CloudFront for dashboard
• DigitalOcean: App Platform for both

See backend/DEPLOYMENT.md for detailed instructions.

🎓 Voice Commands

The system supports 7 voice command families:

1. Start Job — "Start a new job for John Smith"
2. Add Measurements — "Add 100 feet of gutter"
3. Add Materials — "Add 10 sheets of aluminum"
4. Build Quote — "Generate a quote for this job"
5. Schedule Delivery — "Schedule delivery for tomorrow"
6. Message Contractor — "Send a message to the client"
7. Lookup Job — "Look up the previous job for this customer"

📱 Mobile Support

The dashboard is fully responsive and works on:

• Desktop (Chrome, Firefox, Safari, Edge)
• Tablet (iPad, Android tablets)
• Mobile (iPhone, Android phones)

🔐 Security

• Environment variables for sensitive data
• JWT authentication ready
• Email validation
• Input sanitization
• CORS configured for production

📝 License

MIT

🤝 Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Commit changes: git commit -am 'Add feature'
3. Push to branch: git push origin feature/your-feature
4. Open a Pull Request

📞 Support

For issues, questions, or suggestions, please open an issue on GitHub or contact the development team.

🗺 Roadmap

• OpenAI Realtime API integration for live voice transcription
• Advanced analytics dashboard
• PDF quote export
• Customizable email templates per trade
• React Native mobile app
• Multi-language support
• Contractor marketplace
• Integration with accounting software

---

Built with ❤️ for contractors everywhere