Skip to content
TinyPhiPublic

About

A modular, workflow-native business platform. CRM, helpdesk, HRMS, and more — all powered by three shared engines. Self-hostable, extensible, TypeScript.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1,296 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


  ___                 _    _ _         _
 / _ \ _ __  ___ _ _| |  | | |_ _ __ __| |
| (_) | '_ \/ -_) ' \ |/\| | | ' \/ _` |
 \___/| .__/\___|_||_\_/  \_|_|_||_\__,_|
      |_|

A modular, workflow-native business platform.
Built for teams that outgrew their SaaS stack but aren't ready to build from scratch.


License: AGPL-3.0 Built with TypeScript Node.js 22+ PRs Welcome


What is OpenWind?

OpenWind is an open-source, self-hostable business operating platform. It replaces the patchwork of disconnected SaaS tools that most growing businesses accumulate — a helpdesk here, an expense system there, a CRM somewhere else — with a single coherent platform where every module shares the same data layer, auth, workflow engine, and integration infrastructure.

The core insight behind OpenWind is simple:

A support ticket, an expense claim, a sales deal, and a purchase order are all the same thing — a stateful object moving through a workflow. Once you build that engine well, every business process is just configuration on top of it.

OpenWind is built for software engineering teams that want to own their operational stack — either to deploy it internally, extend it for specific customers, or build sector-specific products on top of it.


The three engines

Everything in OpenWind is powered by three shared engines. Modules, sector packages, and custom workflows are all configurations of these engines — not new codebases.

Entity Engine

Define what your business works with. Contacts, tickets, expenses, assets, employees — any entity type, with typed fields, relations, and per-tenant custom fields. No migrations needed when a customer adds a field.

Workflow Engine

Define how things move. A finite state machine for any entity: states, transitions, role-based guards, conditional branching, SLA timers with automatic escalation, and an immutable event log for every transition ever made.

Automation Engine

Define what happens when things move. An event → condition → action pipeline that fires on any state change, field update, or external event. Powers notification routing, assignment rules, cross-system integrations, and SLA enforcement — all from configuration, no code required.


What's included

Core platform

Auth and identity (Zitadel), notifications (Novu), tenant-scoped local-disk file storage with async ClamAV malware scanning, an append-only audit log, secrets management (OpenBao), API gateway, background job queue (BullMQ), a connector runtime with an inbound webhook gateway and polling-connector framework, and a plugin system (Module Federation). Shared by every module — no module reinvents these. Also built in: on-call routing with severity-based notification dispatch, a cron-style schedule-rule scheduler that auto-creates tickets, an org directory (org chart synced from Zitadel user metadata), embedded Superset reporting with tenant isolation (opt-in, --profile reporting), and multi-org sandboxes for trials (provision, reset, handover, expiry). Observability (OpenTelemetry, Prometheus, Sentry) and GDPR-relevant controls (tenant/per-user erasure, configurable retention, IP allowlisting) are built in, not bolted on.

Standard modules

Pre-built applications that install on top of the engines:

Module What it does
CRM Contacts, companies, deals, pipeline, activities
Helpdesk Tickets, SLA, assignments, knowledge base, customer portal
HRMS Employees, org chart, leaves, attendance, onboarding
Reimbursements Expense claims, multi-level approvals, receipt management
Projects Tasks, milestones, sprints, kanban, time tracking
Invoicing Invoices, quotes, payment links, recurring billing
Procurement Purchase orders, vendor management, approval chains
Tender Tender/bid tracking, costing sub-tasks, approval workflow
Vendor Approval Sequential IT Security → Legal → Finance vendor review with SLAs (seed config, 3H Phase 1)

Ticket & record features

Cross-cutting capabilities available to any entity-engine-backed module (helpdesk, tender, and others):

  • Child tickets — break a ticket into sub-tasks with their own workflow state, assignee, and due date. Depth and per-parent count are configurable per workflow (max_child_depth / max_children_per_parent); archiving a parent archives its children too.
  • Access requests — a non-privileged user can request read/comment/write access to a record they don't own; an admin, agent, or the record's owner can approve or reject the request, with a full history event either way.
  • Attachments — file uploads on tickets and comments, backed by tenant-scoped local-disk storage with async ClamAV malware scanning and per-tenant storage quotas.
  • My Tickets — a user-scoped view combining a customer's own tickets, tickets they're mentioned/granted access on, and their children — with per-workflow counts.
  • Severity and tags — tickets carry a severity and free-form tags; severity drives on-call routing and notification policy.
  • Multiple workflow admins — a workflow can have more than one designated admin (assigned_to is a list, not a single user), each with settings access.

Connectors

A connector runtime (inbound webhook gateway with HMAC verification, plus a polling-connector framework for systems with no webhook support) and a tenant-scoped connector credential store, both built and merged. Slack notifications ship today; email (SMTP/IMAP), WhatsApp Business, and a connector marketplace UI are not started yet — see docs/tracker/roadmap-tracker.md (track 3A) for current status before assuming a specific integration is ready to use.


Architecture

┌──────────────────────────────────────────────┐
│            Customer applications             │
│   CRM · Helpdesk · HRMS · Reimbursements    │
├──────────────────────────────────────────────┤
│                Engine layer                  │
│  Entity Engine · Workflow Engine · Automation │
├──────────────────────────────────────────────┤
│             Integration layer                │
│  Event bus · Connector SDK · Webhook gateway │
├──────────────────────────────────────────────┤
│             Platform services                │
│  Auth · Notifications · Files · Audit · API  │
├──────────────────────────────────────────────┤
│               Infrastructure                 │
│  Postgres · PgBouncer · Redis · OpenBao ·    │
│      local disk (files) · ClamAV             │
└──────────────────────────────────────────────┘

Multi-tenant from the ground up, using Postgres Row-Level Security. Every tenant's data is isolated at the database layer — not the application layer. A developer who forgets a WHERE clause gets only their tenant's rows.

Full architecture documentation: docs/architecture-brief.md


Tech stack

Layer Technology Why
API framework Hono TypeScript-first, Web Standards, runs anywhere
Database PostgreSQL 16 RLS multi-tenancy, JSONB, full-text search
ORM Drizzle SQL-transparent, type-safe, great migrations
Queue BullMQ Redis-backed, reliable, good observability
Auth Zitadel OIDC/SAML, org model maps to multi-tenancy
Notifications Novu Multi-channel, templates, user preferences
Admin UI Refine + shadcn/ui CRUD framework + polished components
Reporting Apache Superset Embedded dashboards behind guest tokens, tenant-isolated via a restricted reporting role (opt-in)
Secrets OpenBao Self-hosted secrets management (Vault fork)
Monorepo Turborepo + pnpm Cached builds, clean workspace management
AI Claude (Anthropic) Primary development tooling today; platform AI features (automation-rule generation, digests) are early/in-progress, not yet shipped — see the roadmap

Getting started

Prerequisites

Quick start — one command

git clone https://github.com/TinyPhi/OpenWind.git
cd OpenWind
pnpm install --frozen-lockfile
pnpm bootstrap

The bootstrap script handles everything automatically:

Step What it does
1 Checks Node.js, pnpm, and Docker versions
2 Creates .env.local from .env.example
3 Starts all Docker services (docker compose up -d)
4 Waits for Postgres and Zitadel to be healthy
5 Installs all workspace dependencies
6 Runs database migrations and seeds base data
7 Configures Zitadel (OIDC app, roles, auth credentials)
8 Creates three demo users with different permission levels
9 Seeds a complete Helpdesk demo with 5 sample tickets
10 Prints all URLs and credentials

Fully automated — Bootstrap reads the Zitadel setup token automatically from the container. No browser step, no copy-pasting. Every run is headless.

After bootstrap finishes, everything is already running in Docker. Open http://localhost:3001 and log in.

To rebuild and restart all containers after code changes:

docker compose up -d --build

What you get

URL Service
http://localhost:3001 App — admin, agent, and customer views (RBAC-controlled)
http://localhost:3000 API
http://localhost:3000/docs API docs (Scalar)
http://localhost:8080 Zitadel console

All user types log in at the same URL (http://localhost:3001). The app reads the role from the JWT and shows the appropriate view automatically.

Demo credentials

Username Password Role View shown after login
owAdmin OpenWind1234! Admin Full admin panel
owAgent OpenWind1234! Agent Agent / support view
owUser OpenWind1234! User Customer / portal view

You can also log in with the full email (owAdmin@openwind.local, etc.) — both work.

Username Password Role Access
admin@platform.local Admin1234! System Zitadel console only

Seeded demo data

The bootstrap seeds the module registry (Helpdesk, CRM, HRMS, Reimbursements, Projects, Invoicing, Procurement, Tender) so every template shows up on the Templates page — it does not create any tenant-owned entity types, workflows, or records. Log in and install a module (e.g. Helpdesk) from the Templates page to seed its ticket entity type, 4-state workflow (open → in_progress → pending → resolved), and automation rule into your own tenant.

Resetting everything

docker compose down -v   # removes all container data (volumes wiped)
rm .env.local            # removes your local env + generated credentials
pnpm bootstrap           # full setup from scratch (fully automated, no manual steps)

Important: Always use docker compose down -v (not just down) before re-running bootstrap from scratch. Without -v, Docker preserves the Postgres volume and the old Zitadel data will mix with the new setup.

Full setup guide (local + production): SETUP.md


Project structure

OpenWind/
├── apps/
│   ├── api/          # Hono API server
│   ├── worker/       # BullMQ background workers (outbox, automation,
│   │                 #   SLA, notifications, file scanning, retention)
│   └── admin-ui/     # Refine + shadcn/ui — single app serving admin,
│                     #   agent, and customer views (RBAC-controlled)
│                     #   (apps/portal was removed in PR #211; the
│                     #   directory is a pnpm workspace stub only)
├── packages/
│   ├── db/           # Drizzle schema + migrations
│   ├── entity-engine/
│   ├── workflow-engine/
│   ├── automation-engine/
│   ├── connector-sdk/
│   ├── plugin-sdk/
│   ├── auth/         # Zitadel JWT + RBAC
│   ├── notifications/# Novu wrapper
│   ├── files/        # Local-disk file storage + ClamAV scanning
│   ├── audit/        # Append-only audit log
│   ├── secrets/      # OpenBao client
│   ├── redis/        # Shared client + rate limiting
│   ├── config/       # Zod-validated env vars
│   ├── logger/       # Structured pino logger
│   ├── telemetry/    # OTel/Prometheus/Sentry, usage metering
│   ├── teams/        # Teams/services/on-call-schedule primitives
│   ├── scheduler/    # Schedule-rule cron/next-fire primitives
│   ├── org-directory/# Org chart: importer, tree build, sync, query API
│   ├── ai/           # Anthropic SDK wrapper (early — see roadmap)
│   └── ui/           # Shared design system
├── modules/          # Seed SQL + a one-line stub index.ts per module —
│   ├── crm/          #   no domain-logic TypeScript, ever (ADR-004)
│   ├── helpdesk/
│   ├── hrms/
│   ├── reimbursements/
│   ├── projects/
│   ├── invoicing/
│   ├── procurement/
│   ├── tender/
│   └── vendor-approval/
└── docs/
    ├── architecture-brief.md
    ├── decisions/     # Architecture Decision Records (ADR-001–022)
    └── tracker/roadmap-tracker.md  # live phase/track status

Roadmap

Phase 1 — Foundation ✅ done (2026-05-21) Multi-tenant Postgres/RLS, auth, entity engine, workflow engine, automation engine, API layer, admin shell.

Phase 2 — First customer-ready apps ✅ done (2026-06-18) Helpdesk, reimbursements, CRM, HRMS, projects, invoicing, procurement, tender, admin UI + customer portal views, notification layer, no-code builders.

Phase 3 — Scale & extensibility 🟡 in progress Nine tracks — connector runtime, partner API & marketplace (3A, runtime and partner API shipped; email/WhatsApp connectors and marketplace UI not started), plugin system (3B, ✅ done), AI layer (3C, not started), observability & GDPR compliance (3D, ✅ done), on-call routing & severity notifications (3E, phases 1–4 merged, delivery-channel gaps), scheduler (3F, phases 1–4 merged), MIS/reporting via Superset (3G, stages 1–2 merged; standalone SSO stage off pending review), cross-functional workflow visibility (3H, phase 1 merged), and deferred ops/infra (3-OPS, not started). Two spec-driven efforts sit outside the track table: multi-org sandboxes and the org directory.

Phase 4 — Sector depth (not started) Vertical sector packages, white-label support, advanced analytics.

This project moves fast — treat the summary above as a snapshot, not a commitment. See docs/tracker/roadmap-tracker.md for the live, per-track breakdown with owners and exit criteria, and CLAUDE.md's "Current focus" section for the phase this repo is actively working on right now.


Contributing

OpenWind is built in the open and contributions are welcome. Before opening a PR, please read:

  • CONTRIBUTING.md — how to contribute
  • CLAUDE.md — engineering conventions (also used by our AI development tooling)
  • docs/decisions/ — architecture decision records that explain the why behind key technical choices

Good first issues are tagged good first issue in the issue tracker.

For significant contributions — new modules, changes to the engine layer, new connector types — please open a discussion issue first to align on approach before writing code.


Architecture decision records

Key technical decisions are documented as ADRs in docs/decisions/ — 23 as of this writing, humans-only to write or modify. ADR-018 through ADR-023 are Proposed, not yet accepted:

This list drifts — if it's missing a recent ADR, check docs/decisions/ directly rather than trusting the count above.


License

OpenWind is released under the GNU Affero General Public License v3.0.

This means you can use, modify, and self-host OpenWind freely. If you modify OpenWind and offer it as a service to others, you must release your modifications under the same license.

For commercial licensing (embedding OpenWind in a proprietary product without AGPL obligations), contact abmish@outlook.in.


About TinyPhi

TinyPhi builds open-source infrastructure for teams that need enterprise-grade software without enterprise-grade overhead. OpenWind is our first major open-source project.


Built with TypeScript, Postgres, and a lot of careful thought about workflows.

About

A modular, workflow-native business platform. CRM, helpdesk, HRMS, and more — all powered by three shared engines. Self-hostable, extensible, TypeScript.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages