Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
235 lines (188 loc) · 9.09 KB

DOCUMENTATION.md

File metadata and controls

235 lines (188 loc) · 9.09 KB
Raw

AI Workforce Platform — Project Documentation

Hire AI Employees. Scale Without Hiring.

1. Short Description

AI Workforce Platform is a full-stack SaaS application that lets businesses "hire" and manage AI employees (autonomous agents for support, sales, meetings, HR, invoicing, etc.). Each organization signs up, hires agents, and monitors their work from a premium, dark-themed dashboard. The AI agents are powered by Anthropic's Claude. It's a multi-tenant product: every company's data (users, agents, tasks) is isolated to its own organization.

2. Tech Stack

Layer Technology
Frontend Next.js 15 (App Router), TypeScript, Tailwind CSS v4, Zustand (state), TanStack Query (data), Framer Motion, Recharts, Lucide Icons
Backend Java 21, Spring Boot 3.4 (Web, Data JPA, Security, Validation), Hibernate, HikariCP, JWT (jjwt)
AI Anthropic Claude (claude-opus-4-8) via the official anthropic-java SDK
Database PostgreSQL (Supabase) in prod · file-based H2 for local dev
Auth Stateless JWT (BCrypt-hashed passwords)
Hosting Backend → Render (Docker) · Frontend → Vercel · DB → Supabase
Source GitHub, single repo (monorepo)

3. Architecture (high level)

   Browser ──HTTPS──►  Frontend (Next.js, Vercel)
                              │  fetch() with JWT  → NEXT_PUBLIC_API_URL
                              ▼
                       Backend (Spring Boot, Render, Docker)
                              │  Spring Data JPA / Hibernate
                              ▼
                       PostgreSQL (Supabase)
                              ▲
   AI agent calls  ───────────┘ (aiengine → Anthropic Claude API)
  • Stateless JWT auth — the frontend stores the token and sends it as Authorization: Bearer <jwt> on every request.
  • Multi-tenancy — every domain query is scoped to the caller's organization_id.
  • CORS — the backend allows the frontend origins (localhost + Vercel + Render).

The repo also documents a 5-phase growth vision (monolith → microservices → marketplace) in ARCHITECTURE.md; the folders services/, platform/, mobile-app/, and deploy/ are scaffolding for those future phases.

4. Repository Structure

ai-workforce-platform/
├── frontend/            # Next.js 15 web app  (BUILT, working)
│   └── src/
│       ├── app/         # routes (login, register, onboarding, dashboard, agents, …)
│       ├── components/  # UI + feature components
│       ├── services/    # API clients (api.ts, auth.ts, agents.ts, dashboard.ts, …)
│       ├── hooks/       # React Query hooks
│       ├── store/       # Zustand stores (auth, ui)
│       ├── types/       # shared TS types
│       └── lib/         # utils, constants, mock data
│
├── backend/             # Spring Boot API  (BUILT, working)
│   ├── src/main/java/com/company/
│   │   ├── auth/        # register/login/me  (controller·service·dto)
│   │   ├── user/        # User entity + repo
│   │   ├── organization/# Organization entity + repo
│   │   ├── agents/      # Agent CRUD + AI chat (entity·repo·service·controller·dto)
│   │   ├── dashboard/   # computed dashboard metrics
│   │   ├── aiengine/    # Claude integration (llm·prompts·orchestrator·tools·…)
│   │   ├── security/    # JWT filter, SecurityConfig, CurrentUser
│   │   └── common/      # health endpoint, global exception handler
│   ├── src/main/resources/
│   │   ├── application.yml     # env-driven datasource (Supabase/H2)
│   │   └── prompts/            # agent system prompts (support, sales, …)
│   ├── Dockerfile              # multi-stage build for Render
│   └── pom.xml
│
├── services/ · platform/ · mobile-app/ · deploy/   # Phase 4–5 scaffolding (empty)
├── render.yaml          # Render Blueprint (deploys both tiers)
├── netlify.toml         # alt frontend host config
├── ARCHITECTURE.md      # 5-phase growth roadmap
└── DOCUMENTATION.md     # this file

5. Features

Feature Status Backend-connected?
Landing page ✅ Built n/a (static)
Sign up / Log in (JWT) ✅ Built ✅ Yes (Supabase)
Onboarding wizard ✅ Built (local state)
AI Employees — list / hire / pause / delete ✅ Built ✅ Yes (Supabase)
Dashboard (stats, activity, charts) ✅ Built ✅ Yes (computed from agents)
AI agent chat (Claude) ✅ Built ✅ Yes (needs ANTHROPIC_API_KEY)
Tasks page ⚠️ UI only ❌ mock data (backend pending)
Workflows page ⚠️ UI only ❌ mock data (backend pending)
Analytics page ⚠️ UI only ❌ mock data (backend pending)
Knowledge Base / Billing / Integrations / Settings ⚠️ UI only ❌ mock data (backend pending)

6. Backend — API Endpoints

All endpoints are under /api. Protected endpoints require Authorization: Bearer <jwt>.

Auth (public)

  • POST /api/auth/register — { email, password, name, organizationName } → { token, … }
  • POST /api/auth/login — { email, password } → { token, … }
  • GET /api/auth/me — current user (requires token)

Agents (require token, tenant-scoped)

  • GET /api/agents — list this org's agents
  • POST /api/agents — hire a new agent { name, role, description }
  • GET /api/agents/{id}
  • PUT /api/agents/{id} — update
  • POST /api/agents/{id}/pause · POST /api/agents/{id}/resume
  • DELETE /api/agents/{id}
  • GET /api/agents/roles — available agent roles
  • POST /api/agents/{role}/chat — chat with a Claude-powered agent { message }

Dashboard (require token, tenant-scoped)

  • GET /api/dashboard/stats · /activity · /productivity · /agent-activity · /cost-savings

Health (public)

  • GET /api/health → { "status": "UP" }

7. Database Schema (PostgreSQL / Supabase)

Hibernate auto-creates these tables (ddl-auto: update):

organizations

column type
id bigint (PK)
name varchar
industry varchar
plan varchar (default starter)
created_at timestamp

users

column type
id bigint (PK)
email varchar (unique)
password_hash varchar (BCrypt)
name varchar
role varchar (OWNER/ADMIN/MEMBER)
organization_id bigint (FK → organizations)
created_at timestamp

agents

column type
id bigint (PK)
name, role, description varchar
status varchar (ACTIVE/PAUSED/IDLE/ERROR)
avatar varchar (initials)
tasks_completed, efficiency, average_response_time, success_rate numeric
last_active, created_at timestamp
organization_id bigint (FK → organizations)

8. Running Locally

Prerequisites: JDK 21+, Node 20+.

Backend (defaults to local H2; set Supabase via backend/.env):

cd backend
# optional: use Supabase
set -a && source .env && set +a
./mvnw spring-boot:run          # → http://localhost:8080

Frontend:

cd frontend
npm install
npm run dev                     # → http://localhost:3000

frontend/.env.local controls which backend the frontend calls:

NEXT_PUBLIC_API_URL=http://localhost:8080/api          # local backend
# or https://ai-workforce-backend.onrender.com/api     # cloud backend

Rule: only one backend at a time (port 8080 + the H2/Supabase connection are single-holder).

9. Deployment

Tier Host How
Backend Render (Docker) backend/Dockerfile; env vars SPRING_DATASOURCE_*, JWT_SECRET, CORS_ALLOWED_ORIGINS
Frontend Vercel Root Directory = frontend; env var NEXT_PUBLIC_API_URL
Database Supabase Session pooler (port 5432); HikariCP pool kept small (free-tier 15-connection limit)

render.yaml can deploy both tiers as a single Blueprint. CORS is set to http://localhost:3000,https://*.vercel.app,https://*.onrender.com so local + Vercel frontends are all allowed.

10. Current Status & Roadmap

Working today: Frontend (all pages render) · Auth · AI Employees (CRUD) · Dashboard · AI chat — all persisting to Supabase; backend deployed on Render.

Next up (recommended order):

  1. Tasks backend (entity + endpoints + seed) → lights up the Tasks page + real dashboard/analytics numbers.
  2. Workflows and Analytics backends → wire the last mock pages.
  3. Production hardening — Flyway migrations (ddl-auto: validate), rotate secrets, add tests + CI.
  4. Phases 4–5 — split into microservices (services/), add the marketplace (platform/), mobile app.

Generated as living documentation — update as features land.