WorkFlow

A self-hosted project & knowledge management platform for small engineering teams.

Sprints and tasks, a knowledge base, decision records, release notes, team chat,
a personal note keeper, and status digests — one workspace, one login.

It's a custom PHP MVC application (no framework, no build step) backed by MySQL/MariaDB, designed to run in Docker — clone it, point it at a database, and it's yours.

---

✨ Features

Module	What it does
📊 Dashboard	Per-user overview — active sprints, open tasks, proposed ADRs, priority/due-soon tasks, recent activity
🗂️ Projects & Tasks	Projects → Features / Sprints → Tasks → Subtasks, with task discussions, reference links, CSV import/export, and a pre-flight approval step for new projects
📚 Knowledge Hub	Shared reference library (docs, links, files) organized as a tree, with tags
📝 Any Decision Records (ADRs)	Log decisions with context / decision / alternatives / consequences and a status (Proposed / Accepted / Superseded)
🚀 Release Notes	Versioned changelog entries per project or org-wide
💬 Team Chat	Public channels with @mentions that trigger notifications (HTTP-polled, not real-time)
🧵 Discussions	Workspace/project/member-scoped threads with @mentions, separate from task comments
💡 Ideas	A voteable idea board — promote a winning idea straight into a real feature
🧪 Testing & Feedback	A public (no-login) feedback portal for beta testers, with one-click "convert to task"
🗒️ Note Keeper	Private, per-user notes — global, or scoped to a project, feature, sprint, or task; taggable and searchable
📬 Daily / Weekly Updates	Auto-generated status digest grouped by project → sprint → feature, sent by real SMTP
⚙️ Settings	Workspace branding, SMTP/email config, team member management, an RBAC matrix, and customizable terminology
🔍 Spotlight Search (⌘K)	Cross-module search — projects, tasks, knowledge docs, ADRs, your own notes, people, chat, and task comments; prefix a query with # to search tags

See readme/MODULES.md for a per-module deep dive and readme/ARCHITECTURE.md for how the system is put together.

---

🧱 Tech stack

• Backend: PHP 8.2, plain mysqli (no ORM), a small hand-rolled MVC framework (see readme/ARCHITECTURE.md)
• Database: MariaDB 10.11 (MySQL-compatible)
• Frontend: Server-rendered PHP views, vanilla JS (fetch-based AJAX, no framework, no build step), one shared stylesheet
• Web server: Apache 2.4 (mod_rewrite, .htaccess-driven routing)
• Containerization: Docker Compose (app + db + phpMyAdmin)

---

🚀 Quick start (Docker)

Requires Docker and Docker Compose.

cp .env.example .env
# then edit .env and set WORKFLOW_DB_ROOT_PASSWORD / WORKFLOW_DB_PASSWORD to
# real values, e.g.: openssl rand -base64 24
docker compose up -d --build

This starts three containers:

Service	Container	URL
App (Apache + PHP)	workflow_app	http://localhost:8080
Database (MariaDB)	workflow_db	localhost:3306
phpMyAdmin	workflow_pma	http://localhost:8081

Then open http://localhost:8080 — if config.php doesn't exist yet, you'll be redirected straight to the installer at /setup/index.php. The Database & Branding step is pre-filled with the host/user/database Docker Compose already knows (db / workflow / workflow_platform) and the password you just set in .env — just review and continue.

The installer imports setup/workflow_database.sql into whatever database name you give it, lets you set your workspace name and your own admin email/password, generates a fresh random encryption key for this install (used by Note Keeper and Team Chat field encryption — see readme/ARCHITECTURE.md §6), and writes config.php for you. Nothing here is shared across installs or hardcoded in the repo — there's no credential or key you need to be handed to get running.

No secret ever lives in config.php. It only contains getenv(...) calls — see config.sample.php for the template. The actual database password and encryption key are read from .env (gitignored, chmod 600, generated/updated by the installer). This means the same clone works against different environments without committing real credentials, and a fresh clone with no config.php at all still lands you on the installer instead of a fatal error.

The installer's admin-login form is pre-filled with admin@workflow.local / Welcome123! as a starting point, but you're expected to type in your own values before submitting — see setup/CREDENTIALS.md. If you do leave the pre-filled defaults, change the password in Settings immediately after your first login.

For manual (non-Docker) install steps and troubleshooting, see DOCKER_SETUP.md and setup/README.md.

---

📁 Project structure

ProjIn/
├── index.php              # Single entry point — bootstraps config, session, routes the request
├── config.php              # Environment config (gitignored — see config.sample.php)
├── .env                     # Local secrets (gitignored — see .env.example)
├── .htaccess                  # Apache rewrite rules — routes everything through index.php
├── docker-compose.yml         # app + db + phpmyadmin services
├── Dockerfile                   # Apache + PHP 8.2 image
│
├── system/                  # The framework itself
│   ├── controller.php         # Base Controller (loadModel/loadView/redirect/...)
│   ├── model.php               # Base Model — mysqli connection + query/escape helpers
│   ├── view.php                 # Base View — renders a .phtml inside top/footer chrome
│   ├── pip.php                   # The router: URL segments → Controller::action()
│   ├── env.php                    # Minimal .env parser
│   └── error_handler.php           # PHP error/exception → JSON log file
│
├── application/
│   ├── controllers/          # One class per module (dashboard, projects, adrs, notes, ...)
│   ├── models/                 # Project_model, Auth_model, Rbac_model, Base_model, ...
│   ├── views/                   # One folder per module, .phtml templates
│   └── helper/                   # auth.php (session/permission helpers), upload.php
│
├── assets/                   # app.css, app.js, fonts, images
├── uploads/                   # User-uploaded files (gitignored; script execution blocked)
├── setup/                      # Installer wizard + workflow_database.sql schema
├── websocket_server/            # Node/ws chat server — present but NOT currently wired up
│                                  (Team Chat actually uses HTTP polling; see ARCHITECTURE.md)
└── readme/                       # Deep-dive docs (architecture, modules, database, deployment)

---

📖 Documentation

• readme/ARCHITECTURE.md — request lifecycle, the MVC framework, auth/RBAC, Docker layout, known rough edges
• readme/MODULES.md — what each module does, its routes, controller/view/table map
• readme/DATABASE.md — full schema reference, table by table
• readme/DEPLOYMENT.md — deploying to a real server behind nginx + Certbot: port/disk-space checks on a shared box, the production Compose file's gotchas, the reverse-proxy HTTPS bug, setup-wizard schema-import recovery, and a macOS-vs-Linux case-sensitivity trap — all from an actual deploy, not theory

---

🤝 Contributing

Contributions are welcome — see CONTRIBUTING.md for setup instructions and guidelines. Found a security issue? Please report it privately — see SECURITY.md.

---

📄 License

MIT — see LICENSE. Use it, fork it, self-host it, build on it.

---

_{Built for teams who'd rather ship than fight their tools.}