🧰 Work Suite

A self-hosted productivity platform with AI-friendly tools for developers and power users.

Work Suite provides lightweight, text-based productivity apps that produce traditional artefacts (task boards, timelines, presentations, spreadsheets, documents) using formats that are easy for both humans and LLMs to read, write, and transform — primarily Markdown, JSON, and plain text.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                      Work Suite Platform                             │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                  Frontend Apps (Static HTML)                 │    │
│  │  ┌───────┬───────┬────────┬────────┬────────┬────────┐      │    │
│  │  │ Slate │ Done  │Journey │ Merman │ Metric │Pointer │      │    │
│  │  └───────┴───────┴────────┴────────┴────────┴────────┘      │    │
│  │  ┌───────────────────┬──────────────────────────────┐       │    │
│  │  │ Theme Designer    │         Tags (File Manager)  │       │    │
│  │  └───────────────────┴──────────────────────────────┘       │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│                              ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                 Nginx Reverse Proxy (:8500)                  │    │
│  │  • Serves static HTML files                                  │    │
│  │  • Proxies /api/* → API server                               │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│                              ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                   Work Suite API (:3000)                     │    │
│  │  • Node.js + Express                                         │    │
│  │  • SQLite database (better-sqlite3)                          │    │
│  │  • JWT Authentication with HTTP-only cookies                 │    │
│  │  • WebSocket for real-time sync                              │    │
│  │  • LLM-friendly API endpoints                                │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│              ┌───────────────┼───────────────┐                      │
│              ▼               ▼               ▼                      │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐             │
│  │   Authentik   │ │   Service-0   │ │   SQLite DB   │             │
│  │   (SSO/IdP)   │ │  (Platform)   │ │   (Storage)   │             │
│  └───────────────┘ └───────────────┘ └───────────────┘             │
└─────────────────────────────────────────────────────────────────────┘

📦 The 8 Apps

Core Productivity Apps

App	Icon	Description	Format
Slate	📝	Keyboard-first notes with tile UI	Markdown, JSON
Done	✅	Kanban task board with drag-and-drop	JSON, Markdown
Journey	🛤️	Visual timeline creator	JSON, HTML export
Merman	🐠	Markdown editor with Mermaid diagrams	Markdown
Metric	📊	Spreadsheet with formulas and charts	JSON, CSV
Pointer	👆	Markdown slide presentations	Markdown, JSON

Platform Apps

App	Icon	Description
Tags	🏷️	Central file manager with scopes, folders, tags, and status workflow
Theme Designer	🎨	Create custom themes from images with color extraction

🔐 Access Scopes

Work Suite organizes content into four access scopes:

Scope	Icon	Access Level	Use Case
Me	👤	Owner only	Private drafts, personal notes
Us	👥	Explicit invite	Shared projects, team docs
We	🏢	Team/workspace default	Department resources
There	🌐	External/public	Published content, templates

🚀 Deployment

Prerequisites

Docker and Docker Compose
ZFS storage (recommended) or local filesystem
Authentik instance (for SSO)
Service-0 instance (for workspace management)

Quick Start

# Clone to your server
git clone <your-private-repo> /zfs/data/work_suite/app
cd /zfs/data/work_suite/app/docker

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the stack
docker compose up -d

# View logs
docker compose logs -f

Environment Variables

# Required
JWT_SECRET=your-secure-secret-here

# Authentik OAuth2
AUTHENTIK_URL=http://your-authentik:9500
AUTHENTIK_CLIENT_ID=work-suite
AUTHENTIK_CLIENT_SECRET=your-client-secret
AUTHENTIK_CALLBACK_URL=http://your-server:8500/api/auth/callback
FRONTEND_URL=http://your-server:8500

# Service-0 Platform
SERVICE_0_URL=http://your-service0:8001

# Session
SECURE_COOKIES=false  # Set to true for HTTPS

Ports

Port	Service	Description
8500	nginx	Web UI
8501	node	API Server (internal: 3000)

Storage Structure

/zfs/data/work_suite/
├── worksuite.db       # SQLite database
├── files/             # User-uploaded files
│   ├── me/            # Private scope
│   ├── us/            # Shared scope
│   ├── we/            # Team scope
│   └── there/         # External scope
└── app/               # Application files (this repo)

🔌 API Reference

Authentication

Method	Endpoint	Description
`GET`	`/api/auth/login`	Initiate OAuth2 flow
`GET`	`/api/auth/callback`	OAuth2 callback
`GET`	`/api/auth/session`	Get current session
`GET`	`/api/auth/logout`	Logout

Content Management

Method	Endpoint	Description
`GET`	`/api/items`	List items (filter: scope, folder, app, status, tag)
`GET`	`/api/items/:id`	Get single item
`POST`	`/api/items`	Create item
`PUT`	`/api/items/:id`	Update item
`DELETE`	`/api/items/:id`	Delete item

LLM API

Method	Endpoint	Description
`GET`	`/api/llm/help`	Full API documentation for LLMs
`GET`	`/api/llm/schema/:app`	JSON schema for app content
`GET`	`/api/llm/example/:app`	Example content for app
`POST`	`/api/llm/content/:app`	Create content for app

Workspaces (Service-0)

Method	Endpoint	Description
`GET`	`/api/workspaces`	Get user's workspaces
`POST`	`/api/workspaces`	Create workspace

💾 Data Formats

All apps use simple, text-based formats optimized for LLM workflows.

Universal Document Structure

{
  id: "uuid",
  name: "Document Name",
  type: "file",
  app: "pointer" | "slate" | "done" | "journey" | "merman" | "metric",
  
  // Access Control
  scope: "me" | "us" | "we" | "there",
  owner_id: "user-uuid",
  workspace_id: "workspace-uuid",
  
  // Organization
  folder: "Projects/2024",
  status: "backlog" | "in-progress" | "done" | "closed",
  tags: ["tag1", "tag2"],
  
  // Content (app-specific JSON)
  content: "{ ... }",
  
  // Metadata
  created_at: "2024-01-15T10:30:00Z",
  updated_at: "2024-01-15T11:45:00Z"
}

App Content Examples

Done (Kanban)

{
  "title": "Sprint 42",
  "theme": "slate",
  "columns": [
    {
      "id": "todo",
      "title": "To Do",
      "cards": [
        {
          "id": "card_1",
          "title": "Review PRs",
          "description": "Check pending pull requests",
          "due": "2024-12-01",
          "labels": ["#3b82f6"]
        }
      ]
    }
  ]
}

Pointer (Slides)

{
  "title": "AI Overview",
  "theme": "midnight",
  "slides": [
    {
      "id": 1,
      "layout": "title",
      "content": "# Welcome\n\n## Introduction to AI"
    }
  ]
}

Journey (Timeline)

{
  "title": "Project Roadmap",
  "theme": "emerald",
  "layout": "vertical",
  "events": [
    {
      "id": 1,
      "date": "Q1 2024",
      "title": "Planning Phase",
      "description": "Requirements gathering",
      "icon": "📋"
    }
  ]
}

Merman (Markdown)

{
  "content": "# Architecture\n\n```mermaid\ngraph TD\n  A --> B\n```"
}

🤖 AI Integration

Work Suite is designed for seamless LLM integration:

Discovery

# Get full API documentation
curl http://your-server:8500/api/llm/help

# Get schema for specific app
curl http://your-server:8500/api/llm/schema/pointer

Content Creation

# Create a presentation
curl -X POST http://your-server:8500/api/llm/content/pointer \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI Overview",
    "theme": "midnight",
    "slides": [...]
  }'

Batch Operations

# Create multiple items
curl -X POST http://your-server:8500/api/llm/batch/create \
  -H "Content-Type: application/json" \
  -d '{ "items": [...] }'

🎨 Theme System

Built-in Themes

Category	Themes
Dark	Midnight, Aurora, Ember, Forest, Ocean, Neon
Light	Paper, Minimal, Snow, Rosé
Special	Typewriter, Terminal

Theme Designer

Create custom themes by:

Upload an image
Extract colors automatically
Choose fonts from Google Fonts
Preview with sample content
Save to your theme library

⌨️ Keyboard Shortcuts

Global (Tags)

Shortcut	Action
`/`	Focus search
`N`	New file menu
`Ctrl+Click`	Multi-select

Pointer (Presentations)

Shortcut	Action
`←` `→`	Navigate slides
`N`	New slide
`F`	Fullscreen/present
`Esc`	Exit presentation

Slate (Notes)

Shortcut	Action
`N`	New note
`↑↓←→`	Navigate tiles
`⌘K`	Command palette

🔧 Management

# Stop
docker compose down

# Restart
docker compose restart

# Rebuild after code changes
docker compose up -d --build

# View API logs
docker logs -f worksuite-api

# Backup database
cp /zfs/data/work_suite/worksuite.db \
   /zfs/data/work_suite/backups/worksuite-$(date +%Y%m%d).db

📚 Related Documentation

PLATFORM_SPEC.md — Platform architecture and roadmap
PRODUCT_REVIEW.md — Detailed feature documentation
docker/README.md — Docker deployment details

📜 License

MIT License — Use freely in personal and commercial projects.

Work Suite — AI-friendly productivity for your infrastructure. 🧰

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
docker		docker
themes		themes
.DS_Store		.DS_Store
PLATFORM_SPEC.md		PLATFORM_SPEC.md
PRODUCT_REVIEW.md		PRODUCT_REVIEW.md
README.md		README.md
done.html		done.html
index.html		index.html
journey.html		journey.html
merman.html		merman.html
metric.html		metric.html
pointer.html		pointer.html
slate.html		slate.html
tags.html		tags.html

languageseed/work_suite

Folders and files

Latest commit

History

Repository files navigation