Sable

Sable is a multi-workspace employee-intelligence prototype that helps managers notice sustainable-workload signals early and start better, evidence-led conversations. It brings together permissioned engineering activity, employee-owned identity connections, end-of-day updates, and optional AI-assisted summaries so that people can be supported before work pressure becomes invisible.

Employees are an organisation's most important asset, and, more importantly, they are people whose time, health, and ability to do good work deserve care. Sable is designed to make that care more practical: it gives a manager enough context to ask a thoughtful question, discuss workload, and remove blockers. It is not a surveillance tool, a medical product, a performance-ranking system, or an automated employment-decision system.

Status: hackathon prototype. The project includes privacy and review controls, but it has not been independently security-, legal-, or compliance-audited for production use.

Workload strain is costly to employees and organisations, but it should not be reduced to a single score or inferred as a health diagnosis. The World Health Organization describes burn-out in ICD-11 as an occupational phenomenon resulting from chronic workplace stress that has not been successfully managed; it is not a medical condition. WHO: Burn-out as an occupational phenomenon

The evidence gives a strong reason to take early, humane action:

• In a Gallup study of nearly 7,500 full-time employees, 23% reported feeling burned out very often or always, and a further 44% reported it sometimes. Employees who reported frequent burnout were more likely to take sick leave and to be actively looking for another job. Gallup: Employee Burnout, Part 1
• A 2017 systematic review of prospective studies found occupational outcomes associated with job burnout, including job dissatisfaction, absenteeism, presenteeism, and disability-pension outcomes. The review analysed 36 studies that met its quality criteria. Salvagioni et al., PLOS ONE

Sable does not claim to diagnose, predict, or prevent burnout. No dashboard can do that alone. Its intended contribution is earlier visibility of approved work signals, employee context, and clear evidence so a human manager can have a supportive check-in, rebalance work, clarify priorities, or offer appropriate support. Whether those interventions improve outcomes must be evaluated by each organisation rather than assumed.

Sable belongs to an existing, valuable landscape of employee experience, workplace analytics, coaching, and engineering-intelligence products. For example, Microsoft Viva provides workplace analytics and feedback capabilities, Culture Amp focuses on employee experience and listening, and BetterUp's Viva partnership combines coaching with workplace insights.

Sable's prototype focus is narrower and workflow-led: a manager creates a workspace, employees join through secure invites and connect their own work identities, approved activity is normalised, and workload indicators are reviewed with evidence and human judgment. It does not claim feature parity with, or superiority to, those established products. It also does not replace an HRIS, clinical support programme, employee-assistance programme, or formal performance-management process.

Admin account
  -> creates one or more workspaces and departments
  -> connects organisation-level sources and sends secure invite links
  -> employee accepts an email-bound invite
  -> employee connects or claims their own GitHub/Jira identity and can submit EOD updates
  -> approved events and EOD status are normalised within that workspace
  -> deterministic workload signals and optional Groq analysis are produced
  -> department head or manager reviews evidence and starts a supportive conversation

• Multi-workspace onboarding with account roles, organisation scoping, departments, workspace memberships, and secure invitations.
• Employee-owned GitHub and Jira identity connections after joining a workspace.
• GitHub App/OAuth connection, webhook ingestion, and activity sync.
• Jira OAuth connection and activity sync.
• Slack OAuth and alert delivery. Sable does not ingest or analyse Slack message content.
• Approved PTO CSV import for structured absence data, matched to an existing employee email.
• Employee end-of-day updates and manager-facing EOD summary/history views.
• Deterministic workload indicators with evidence, notification/audit records, and an optional review-only Groq analysis layer.
• Employee-specific AI chat grounded in an approved context and evidence allow-list.
• Custom-connector framework for REST polling, signed inbound webhooks, and CSV imports, with mapping/run history and encrypted credentials.
• Two synthetic presentation workspaces in frontend-demo, including an optional server-side Groq demo chat. They do not read from a real Supabase workspace or a connected employee account.

Google Calendar OAuth configuration is present, but calendar activity ingestion is not presented as a completed production workflow in this repository.

Sable treats intelligence as a prompt for care, not a verdict about a person.

• Workload indicators are not performance ratings, medical diagnoses, personality assessments, or protected-trait inferences.
• Groq output is constrained to structured, evidence-grounded responses and is marked for human review. It must not make employment decisions.
• The employee chat context intentionally excludes Slack/private-message content, personal tokens, raw commit diffs, ticket bodies, and raw EOD narratives.
• Supabase migrations use organisation identifiers and Row Level Security policies for browser access. Trusted Flask server requests use a service-role key, which bypasses RLS; that key must remain server-only.
• The current legacy browser-side multi-workspace policy selects an earliest membership for compatibility. Flask applies explicit organisation scoping, but the browser-side RLS design needs redesign and review before claiming full multi-workspace production isolation.
• Provider credentials and custom-connector secrets are encrypted at rest by the backend. Do not place any secret in NEXT_PUBLIC_* variables or commit .env files.
• A security, privacy, data-retention, access-control, and legal review is required before any real organisation uses Sable in production.

Next.js client (frontend-demo)
  -> Supabase Auth for browser session
  -> Flask API for workspace, integration, EOD, and intelligence actions
       -> Supabase Postgres and RLS-backed schema
       -> GitHub, Jira, Slack, HRIS CSV, and custom connector services
       -> Optional Groq API for structured analysis and chat

backend/             Flask API, integrations, scoring, Groq services, and Vercel function
frontend-demo/       Primary Next.js application and synthetic presentation workspaces
frontend/            Separate Vite/React client; not required for the primary local flow
migrations/          Ordered Supabase/Postgres schema migrations and RLS policies
backend/data/         Local/demo data, including sample PTO data
burnout-agent-spec.md Product goals and safety intent

Useful implementation references:

• API and sprint contract
• Supabase migration guide
• Backend environment template
• Frontend environment template

The commands below are written for Windows PowerShell, which is the development environment used for this repository. Use Python 3.10 or newer and a current Node.js LTS release. GitHub, Jira, Slack, Google, and Groq credentials are not required to start the application; they are required only when testing the corresponding integration or AI feature.

1. Create a Supabase project.

2. Open its SQL Editor.

3. Run the files in migrations/ in this exact numeric order:

   001_initial_supabase_schema.sql
   002_connector_credentials.sql
   003_activity_event_idempotency.sql
   004_sprint2_workspace_ai_custom_connectors.sql
   005_employee_ai_chat.sql
   006_enable_ai_monitoring.sql
   007_multi_workspace_eod.sql
   008_eod_submission_timestamp.sql
   

4. Copy the Supabase project URL, anon key, and service-role key. The service-role key is backend-only.

See the migration guide for what each migration adds. Apply them once per development database; do not rerun a migration that has already succeeded unless you understand the SQL effect.

Open a PowerShell terminal at the repository root:

Set-Location .\backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env

Edit backend/.env. For the authenticated workspace flow, set at least:

FLASK_ENV=development
PORT=5000
APP_BASE_URL=http://localhost:5000
FRONTEND_ORIGIN=http://localhost:3000,http://127.0.0.1:5173
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_server_only_service_role_key
CONNECTOR_ENCRYPTION_KEY=your_fernet_key

Generate CONNECTOR_ENCRYPTION_KEY rather than inventing one:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Start the API:

python run.py

Verify the backend in a browser or terminal:

http://localhost:5000/health

Open a second PowerShell terminal at the repository root:

Set-Location .\frontend-demo
Copy-Item .env.local.example .env.local
npm.cmd install
npm.cmd run dev

Edit frontend-demo/.env.local before signing in:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_API_BASE_URL=http://localhost:5000

Open http://localhost:3000. The intended first-run flow is:

1. Create an account or sign in.
2. Select the admin role.
3. Create a workspace and departments.
4. Send an invite link to an employee.
5. Accept the invite as that employee and connect the employee's own GitHub/Jira identity.
6. Return as an admin, select the workspace, and trigger individual or bulk sync/review actions.

The separate frontend/ Vite client is optional and is not needed for this primary flow. If you explicitly want to run it, copy its .env.local.example, install dependencies, and run npm.cmd run dev from frontend/; it uses port 5173 by default.

Use backend/.env.example as the authoritative list. Do not copy real values into documentation, source code, or browser-visible variables.

For any OAuth or webhook provider, the callback base is derived from APP_BASE_URL:

{APP_BASE_URL}/api/connectors/{provider}/callback

For local provider testing, expose the Flask backend through an HTTPS tunnel, set APP_BASE_URL to that public URL, restart Flask, and register the exact resulting callback URL in the provider dashboard. A provider will reject a callback URL that differs by scheme, host, path, or trailing slash.

Groq is optional. The core workspace flow works without it. To enable review-only AI analysis and the protected presentation chat, add the following to backend/.env:

GROQ_API_KEY=your_groq_api_key
GROQ_ENABLED=true
GROQ_MODEL=llama-3.3-70b-versatile
DEMO_AI_CHAT_ENABLED=true
DEMO_AI_CHAT_TOKEN=generate_a_long_private_shared_token

Then add the matching private presentation configuration to frontend-demo/.env.local:

DEMO_AI_CHAT_API_URL=http://localhost:5000
DEMO_AI_CHAT_TOKEN=the_same_private_shared_token

The browser sends demo requests to a Next.js server route. That route forwards the private token to Flask; the Groq key is not exposed to the browser. If Groq is not configured or its output fails Sable's structured safety contract, the demo returns an explicit error instead of a fabricated answer.

With both services running:

Invoke-WebRequest http://localhost:5000/health | Select-Object -ExpandProperty Content

Set-Location .\frontend-demo
npm.cmd run build

Run the frontend build after stopping its development server if a stale Next.js cache causes a local module error. Deleting .next/ is a local build-cache reset only; do not delete source files or configuration to resolve it.

• SUPABASE_SERVICE_ROLE_KEY, provider client secrets, GitHub private keys, webhook secrets, Groq keys, and connector encryption keys are server secrets. They belong only in backend/.env or a server-side hosting environment.
• NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are browser configuration values. Do not give them service-role privileges.
• Never prefix DEMO_AI_CHAT_TOKEN, a GitHub private key, or any provider secret with NEXT_PUBLIC_.
• Rotate any credential that has been pasted into a chat, committed, shared in a screenshot, or put into a tracked example file.
• The documented local secret files, backend/.env and frontend-demo/.env.local, are ignored. Confirm with git status before committing.

frontend-demo includes two public, synthetic presentation routes:

• /demo — administrator view for Northstar Labs.
• /demo/employee — employee view for Orbit Product Collective.

They are intentionally separate from real workspaces, Supabase records, and connected accounts. They are useful for demonstrating the product flow and visualisation without exposing real employee data.

Before a real deployment, at minimum:

• complete a threat model, penetration test, and Supabase RLS/service-role review;
• define access roles, departmental visibility, retention, deletion, audit, and incident-response policies;
• obtain legal, privacy, HR, and worker-representation review appropriate to each jurisdiction;
• validate provider scopes, webhook verification, rate limits, error handling, and tenant-isolation tests;
• establish consent and transparency practices for every collected signal;
• validate whether workload indicators are fair, useful, and non-discriminatory for the intended population;
• train managers to use signals for supportive conversations, not performance ranking or employment decisions;
• measure outcomes before making claims about wellbeing, retention, or burnout reduction.

Sable was developed during a rapid two-day hackathon challenge with Codex as an implementation collaborator. The team used Codex's Ultra multi-agent workflow to work on independent implementation and review tasks in parallel, inspect the repository, and move quickly across backend, frontend, integrations, migration work, debugging, and UI refinement.

Codex was used to:

• turn evolving product requirements into concrete flows for workspace creation, invitations, employee identity connection, sync, EOD updates, and manager review;
• review code and pull-request-level changes, trace integration failures, and make logic and UI adjustments through repeated back-and-forth decisions;
• reason from the existing repository context rather than requiring a manually assembled specification for every change;
• use the Firecrawl research skill to gather the external wellbeing and product-landscape sources cited in this README; and
• accelerate implementation while keeping final product decisions with the human team.

This describes the development workflow, not an assertion that Codex makes employment, wellbeing, or managerial decisions inside Sable. Sable's optional Groq features remain evidence-constrained and human-review-oriented.