___ _ _ _ _
/ _ \ _ __ ___ _ _| | | | |_ _ __ __| |
| (_) | '_ \/ -_) ' \ |/\| | | ' \/ _` |
\___/| .__/\___|_||_\_/ \_|_|_||_\__,_|
|_|
A modular, workflow-native business platform.
Built for teams that outgrew their SaaS stack but aren't ready to build from scratch.
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.
Everything in OpenWind is powered by three shared engines. Modules, sector packages, and custom workflows are all configurations of these engines — not new codebases.
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.
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.
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.
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.
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) |
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_tois a list, not a single user), each with settings access.
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.
┌──────────────────────────────────────────────┐
│ 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
| 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 |
- Node.js 22+
- pnpm 11+ (
npm install -g pnpm) - Docker Desktop (running)
git clone https://github.com/TinyPhi/OpenWind.git
cd OpenWind
pnpm install --frozen-lockfile
pnpm bootstrapThe 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| 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.
| 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 |
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.
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 justdown) 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
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
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.
OpenWind is built in the open and contributions are welcome. Before opening a PR, please read:
CONTRIBUTING.md— how to contributeCLAUDE.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.
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:
- ADR-001: Multi-tenancy architecture
- ADR-002: Workflow engine state machine design
- ADR-003: Entity field validation strategy
- ADR-004: Config-first module design
- ADR-005: Module optionality & tender
- ADR-006: Per-workflow ownership/admin model
- ADR-007: RLS for workflow config tables
- ADR-008: API key credential lifecycle hardening
- ADR-009: Connector runtime & webhook gateway architecture
- ADR-010: Inbound partner API integration
- ADR-011: Plugin system
- ADR-012: Third-party API ticket access
- ADR-013: Unified rate-limiting strategy
- ADR-014: Notification SLA retry & escalation
- ADR-015: Observability & compliance
- ADR-016: On-call routing
- ADR-017: Temporal scheduler
- ADR-018: AI layer
- ADR-019: Reporting tenant isolation
- ADR-020: Module ownership model
- ADR-021: Ticket relations & participant access
- ADR-022: Sandboxing
- ADR-023: OpenBao secrets manager
This list drifts — if it's missing a recent ADR, check docs/decisions/
directly rather than trusting the count above.
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.
TinyPhi builds open-source infrastructure for teams that need enterprise-grade software without enterprise-grade overhead. OpenWind is our first major open-source project.