OpenDecisionFlow

Build and share interactive decision trees in a simple web app.

Report Bug · Request Feature

---

Table of Contents

1. About
2. Stack
3. Self-host
4. Quick Start
5. HTTPS
6. Configuration
7. Project Structure
8. Node Types
9. Security
10. Contributing
11. License
12. Contact

---

Screenshots

About

Easy, Free, Opensource

No SaaS, no tracking, no nonsense. Run it yourself, on your server, and own the data completely!

quick overview of the features :

• Decision trees - questions with branching choices, free-text inputs, date pickers, final result
• Auth - server-side sessions, httpOnly cookie, bcrypt passwords
• Access control - public questionnaires, private ones behind an access code, guest mode (no account required)
• Share page - every questionnaire has a shareable link with title, description, and author
• Response history - per-user and per-questionnaire history (public or private)
• Rate limiting - configurable per route, out of the box
• Docker ready - HTTP by default, HTTPS via Caddy with automatic Let's Encrypt

(back to top)

Stack

Layer	Tech
Frontend	React 19 + Vite
Backend	Hono + Bun
Database	SQLite (bun:sqlite)
Reverse proxy	nginx (container) + optional Caddy (HTTPS)
CI/CD	GitHub Actions, GHCR

(back to top)

Self-host ( fastest way to )

Requirements: a machine with Docker. No domain needed.

curl -O https://raw.githubusercontent.com/Elxss/OpenDecisionFlow/main/docker-compose.yml

you should edit it, for it to fit your needs

then you can compose up using

docker compose up -d

Open http://localhost. Default account: admin / admin - you'll be asked to change the password on first login.

Optionally set credentials before starting:

ADMIN_USERNAME=myname ADMIN_PASSWORD=mypassword docker compose up -d

To update:

docker compose pull
docker compose up -d

(back to top)

Quick Start

Requirements: Bun ≥ 1.0

# Terminal 1 - backend
cd backend
cp .env.example .env
bun install
bun run dev

# Terminal 2 - frontend
cd frontend
bun install
bun run dev

Open http://localhost:5173.
Default account: admin / admin - change it.

(back to top)

HTTPS

Requires a domain pointing to your server and ports 80/443 open. Clone the repo first.

1. Edit docker-compose.yml - set CORS_ORIGIN to https://yourdomain.com and COOKIE_SECURE to true.

2. Ensure DNS points to your server and ports 80/443 are open.

3. Start:

DOMAIN=yourdomain.com docker compose -f docker-compose.yml -f docker-compose.https.yml up -d

Caddy fetches the Let's Encrypt certificate automatically on first boot.

(back to top)

Configuration

backend/.env (copy from backend/.env.example):

# Admin account - set before first run
# If omitted, created as admin / admin with a forced password change on first login
ADMIN_USERNAME=admin
ADMIN_PASSWORD=changeme

PORT=3001
CORS_ORIGIN=http://localhost:5173
COOKIE_SECURE=false
DB_PATH=./data.db

SESSION_DURATION_DAYS=7

# Rate limiting (requests per minute)
RATE_WINDOW_MS=60000
RATE_LIMIT_AUTH=10
RATE_LIMIT_STRICT=20
RATE_LIMIT_SEARCH=10
RATE_LIMIT_DECISIONFLOW=15

(back to top)

Project Structure

backend

Contains the API built with Hono and the SQLite database layer.

• index.js: main entry point (routes, middleware, rate limiting)
• db.js: database setup and migrations
• Dockerfile: backend container configuration
• .env.example: environment variables template

---

frontend

Frontend application handling the user interface and client-side logic.

• src/pages/: main views (Dashboard, Questionnaire, History, etc.)
• src/components/: reusable UI components (Navbar, Pagination)
• src/context/: global state management (AuthContext)
• src/api/mock.js: API abstraction layer (mock requests)
• nginx.conf: Nginx configuration (SPA routing + /api proxy)
• Dockerfile: frontend container configuration

---

docker-compose.yml

HTTP stack - pulls prebuilt images from GHCR.

docker-compose.https.yml

HTTPS override - adds Caddy with automatic Let’s Encrypt.

Caddyfile

Reverse proxy configuration and TLS setup.

.github/workflows/ci.yml

CI pipeline for building and pushing Docker images to GHCR.

(back to top)

Node Types

{ "type": "question", "text": "Your question?", "branches": { "Yes": {}, "No": {} } }
{ "type": "action",   "text": "Final result" }
{ "type": "text",     "text": "Your name?",    "key": "name", "next": {} }
{ "type": "date",     "text": "Which date?",   "key": "date", "next": {} }

(back to top)

Security

• Passwords hashed with bcrypt
• Server-side sessions (httpOnly cookie, 256-bit token)
• Parameterized SQL queries throughout
• CORS restricted to the configured origin
• CSRF protection via SameSite=Lax
• Rate limiting on all sensitive routes
• Backend container runs as non-root user

(back to top)

Contributing

1. Fork the repo
2. Create a branch (git checkout -b feature/my-feature)
3. Copy backend/.env.example -> backend/.env
4. Run in dev (see Quick Start)
5. Open a pull request against main

(back to top)

License

MIT

(back to top)

Contact

Elxss - elxssgitcontact@gmail.com - elxss.me

(back to top)