Skip to content

Commit 5228517

Browse files
MertenDMertenD
committed
Add project overview and architecture docs
1 parent f0dc230 commit 5228517

9 files changed

Lines changed: 327 additions & 2 deletions

File tree

‎next.config.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ const withMDX = createMDX();
77
/** @type {import('next').NextConfig} */
88
const nextConfig = {
99
reactStrictMode: true,
10+
images: {
11+
domains: ['skillicons.dev'],
12+
},
1013
};
1114

1215
export default withNextIntl(

‎public/assets/Bachelorarbeit-Merten-Dieckmann.pdf‎

1.37 MB
Binary file not shown.

‎public/assets/cicd.png‎

10.7 KB
Loading

‎public/assets/engine-overview.png‎

29.2 KB
Loading

‎src/content/docs/architecture/deployment.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Deployment
3+
description: How ProcessFlow is built, published, and deployed using GitHub Actions, Docker Hub, Supabase, Traefik, and Watchtower.
4+
---
5+
6+
import { Github, Server, Cloud, Play, RefreshCw, Settings } from 'lucide-react';
7+
8+
## <Play className="inline h-6 w-6 mr-2" /> Deployment Overview
9+
10+
A concise guide to the **CI/CD pipeline**, **hosting architecture**, and **deployment workflow** for ProcessFlow, from code commit to a running production environment.
11+
12+
---
13+
14+
### <Github className="inline h-5 w-5 mr-2 text-secondary" /> CI/CD Pipeline (GitHub Actions)
15+
16+
1. **Trigger**: On push to `main` or manual dispatch.
17+
2. **Build & Publish**:
18+
- Checkout code
19+
- Set up Docker Buildx
20+
- Authenticate to Docker Hub
21+
- Build the Next.js Docker image
22+
- Push `mertend/process-flow:latest` to Docker Hub
23+
3. **Database Migrations**:
24+
- Install Supabase CLI
25+
- Link to production project
26+
- Run `supabase db push` to apply migrations
27+
28+
![CI/CD Workflow](/assets/cicd.png)
29+
30+
---
31+
32+
### <Cloud className="inline h-5 w-5 mr-2 text-secondary" /> Hosting Components
33+
34+
| Component | Role |
35+
| -------------- | -------------------------------------------------------------------- |
36+
| **Supabase** | Hosted PostgreSQL, Auth, Realtime (engine logic execution) |
37+
| **Docker Hub** | Image registry for `mertend/process-flow:latest` |
38+
| **Ubuntu Server** | Runs Docker Compose, Traefik, and Watchtower on a Linux server and hosts the app |
39+
40+
---
41+
42+
### <Server className="inline h-5 w-5 mr-2 text-secondary" /> Server Deployment (Docker Compose)
43+
44+
The Ubuntu host uses this `docker-compose.yml`:
45+
46+
```yaml
47+
services:
48+
app:
49+
container_name: process-flow
50+
image: mertend/process-flow:latest
51+
env_file:
52+
- .env
53+
networks:
54+
- web
55+
restart: unless-stopped
56+
labels:
57+
- traefik.enable=true
58+
- traefik.http.routers.process-flow.rule=Host(`processflow.mertendieckmann.de`) || Host(`www.processflow.mertendieckmann.de`)
59+
- traefik.http.routers.process-flow.entrypoints=websecure
60+
- traefik.http.routers.process-flow.tls=true
61+
- traefik.http.routers.process-flow.tls.certresolver=lets-encrypt
62+
- traefik.docker.network=web
63+
- com.centurylinklabs.watchtower.enable=true
64+
65+
networks:
66+
web:
67+
external: true
68+
```
69+
70+
- **Container Name**: `process-flow` for easy identification.
71+
- **Image**: `mertend/process-flow:latest` from Docker Hub.
72+
- **Restart Policy**: `unless-stopped` to ensure the app runs continuously.
73+
- **Network** `web` connects Traefik and the app.
74+
- **Traefik labels** configure routing, HTTPS, and auto-reloading by Watchtower.
75+
76+
---
77+
78+
### <RefreshCw className="inline h-5 w-5 mr-2 text-secondary" /> Automatic Updates (Watchtower)
79+
80+
There runs a **Watchtower** container on the Ubuntu server that:
81+
82+
- Continuously checks Docker Hub for new `:latest` tags.
83+
- Stops the running `process-flow` container.
84+
- Pulls the updated image and restarts the container with existing settings.
85+
- Ensures minimal downtime when combined with Traefik’s load balancing.
86+
87+
---
88+
89+
### <Settings className="inline h-5 w-5 mr-2 text-secondary" /> Traffic Routing (Traefik)
90+
91+
- **Entrypoint**: `websecure` (HTTPS port 443).
92+
- **TLS**: Managed by Let’s Encrypt via the `certresolver`.
93+
- **Router Rule**: Matches both `processflow.mertendieckmann.de` and `www.processflow.mertendieckmann.de`.
94+
- **Network**: Attached to the external `web` network for service discovery.
95+
96+
---
97+
98+
### <Cloud className="inline h-5 w-5 mr-2 text-secondary" /> Supabase Management
99+
100+
Supabase is hosted via the official dashboard:
101+
102+
- **Database**: PostgreSQL for data storage and engine logic.
103+
- **Auth**: User authentication and security.
104+
- **Realtime**: Live updates for client dashboards.
105+
- **Migrations**: Automatically applied by the CI/CD workflow.
106+
107+
---
108+
109+
*This deployment setup provides a robust, automated path from code to production—with secure routing and continuous updates.*
110+

‎src/content/docs/architecture/meta.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"title": "Architecture",
3+
"pages": [
4+
"process-engine",
5+
"deployment"
6+
]
7+
}

‎src/content/docs/architecture/process-engine.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Process Engine
3+
description: An inside look at how ProcessFlow’s Process Engine drives workflow execution with database functions and triggers.
4+
---
5+
6+
import { Cpu, Database, Zap, RefreshCw, Code, SendToBack } from 'lucide-react';
7+
8+
## <Cpu className="inline h-5 w-5 mr-2 text-secondary" /> Process Engine Architecture
9+
10+
ProcessFlow’s engine is built directly into the database (via Supabase/PostgreSQL), using stored functions, triggers, and JSONB data to model, execute, and advance workflow instances without a separate execution service. This approach ensures that processes can run in the background without the need to have the web application open, and it allows for easy scaling and management of process instances.
11+
12+
---
13+
14+
### <SendToBack className="inline h-5 w-5 mr-2 text-secondary" /> High-Level Engine Overview
15+
16+
To visualize the core lifecycle without diving into low-level SQL, here’s a simplified flowchart:
17+
18+
![Engine Overview Diagram](/assets/engine-overview.png)
19+
20+
This overview shows how tasks move from creation to completion and cycle until the workflow reaches an end node.
21+
22+
---
23+
24+
### <Database className="inline h-5 w-5 mr-2 text-secondary" /> Core Components
25+
26+
- **Web Application**: Frontend and API Endpoint (Next.js) that start processes and displays tasks.
27+
- **Database (Supabase/PostgreSQL)**: Stores process models, instances, flow elements, and data objects. Acts as the execution engine via PL/pgSQL.
28+
- **External Task Servers**: Optional HTTP endpoints that render and collect user task input when an element is marked “Manual” or that automatically execute business logic when an element is marked “Automatic”.
29+
30+
---
31+
32+
### <RefreshCw className="inline h-5 w-5 mr-2 text-secondary" /> Lifecycle of a Process Instance
33+
34+
1. **create_process_instance** (`PL/pgSQL` function) is invoked with a model ID. It:
35+
- Validates a single `startNode` and at least one `endNode` in the model.
36+
- Inserts a new `process_instance` row (status = Running).
37+
- Creates the first `flow_element_instance` for the `startNode` and immediately marks it Completed.
38+
39+
2. **create_next_flow_element_instance** (`AFTER UPDATE` trigger) fires when any flow element instance transitions to Completed. It:
40+
- Reads the completed element’s type (`startNode`, `activityNode`, `gatewayNode`, `endNode`, etc.).
41+
- Determines the next element ID via the corresponding element table (`start_element`, `activity_element`, `gateway_element`, …).
42+
- Inserts a new `flow_element_instance` for that next element (or, if at an `endNode`, marks the process_instance Completed).
43+
44+
3. **execute_created_flow_element_instance** (`AFTER INSERT` trigger) runs on new `flow_element_instance` rows with status = Created. It:
45+
- Skips `startNode` and `endNode` (automatically completed).
46+
- For **gatewayNodes** and **endNodes**, immediately marks them Completed.
47+
- For **Manual** elements, sets status = Todo so it appears in the user’s Task list.
48+
- For **Automatic** elements, sets status = In Progress and issues an HTTP POST to the element’s `execution_url`, passing the instance ID and any JSONB data payload.
49+
50+
4. **complete_flow_element_instance** (`PL/pgSQL` function) is called by the app’s API when a user or external service finishes a task. It:
51+
- Inserts or updates rows in `data_object_instance` to capture output data.
52+
- Sets the corresponding `flow_element_instance` row status = Completed, recording a timestamp.
53+
54+
5. **Cycle Continues**: Completion of any element triggers step 2 again, advancing the workflow until an `endNode` completes and the process instance status flips to Completed.
55+
56+
---
57+
58+
### <Zap className="inline h-5 w-5 mr-2 text-secondary" /> Triggers & Functions
59+
60+
| Trigger / Function | Purpose |
61+
| ------------------------------------------ | ----------------------------------------------------- |
62+
| `create_process_instance()` | Validates model and seeds first element instance |
63+
| `create_next_flow_element_instance` (TRG) | Advances to the next flow element upon completion |
64+
| `execute_created_flow_element_instance` | Routes new instances to Todo or issues auto HTTP call |
65+
| `complete_flow_element_instance()` | Persists outputs and marks an instance Completed |
66+
67+
---
68+
69+
### <Code className="inline h-5 w-5 mr-2 text-secondary" /> Manual vs. Automatic Execution
70+
71+
- **Manual**: Elements with `execution_mode = 'Manual'` are created with status Todo. Users see them in their worklist, open them (via iframe HTTP calls), submit results, and the API invokes `complete_flow_element_instance()`.
72+
- **Automatic**: Elements with `execution_mode = 'Automatic'` go In Progress immediately. The trigger POSTS to the configured `execution_url` and relies on the callback endpoint (`/api/instance/complete`) to finalize.
73+
74+
---
75+
76+
### <Database className="inline h-5 w-5 mr-2 text-secondary" /> Data Objects & Storage
77+
78+
- **Flow Element Definitions** reside in `flow_element`, `activity_element`, `gateway_element`, etc., including JSONB `data` for conditional logic or input parameters.
79+
- **Instance Data**: `flow_element_instance` tracks each element’s runtime status, timestamps, and parent `process_instance`.
80+
- **Output Data**: `data_object_instance` stores arbitrary JSONB key/value pairs per instance, allowing downstream tasks or analytics to consume results.
81+
82+
---
83+
84+
*With this design, ProcessFlow achieves a **serverless**, scalable process engine fully driven by database logic—simplifying deployment and ensuring strong data consistency.*
85+

‎src/content/docs/index.mdx‎

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,122 @@
11
---
22
title: Project Overview
3-
---
3+
description: ProcessFlow is a gamified business process management tool developed as part of a Master’s program at Ulm University.
4+
---
5+
6+
import { Rocket, Search, Target, Settings, Database, Eye, BookOpen } from 'lucide-react';
7+
8+
## <Rocket className="inline h-6 w-6 mr-2 text-secondary" /> Project Overview
9+
10+
**ProcessFlow** is a **gamified** business process management tool developed as part of a Master’s program at Ulm University. It helps teams design, manage, and monitor workflows in real time, while gamification elements such as points, levels, and badges drive motivation and engagement.
11+
12+
---
13+
14+
### <Search className="inline h-5 w-5 mr-2 text-secondary" /> What is ProcessFlow?
15+
16+
ProcessFlow is an intuitive web application for modeling, executing, and tracking business processes. With a drag-and-drop editor, users can quickly build workflows, define custom activities, and assign role-based permissions to team members.
17+
18+
---
19+
20+
### <Target className="inline h-5 w-5 mr-2 text-secondary" /> Why ProcessFlow?
21+
22+
- **Engagement through Gamification**
23+
Points, levels, and badges transform routine tasks into rewarding experiences.
24+
25+
- **Increased Productivity**
26+
Real-time monitoring surfaces bottlenecks immediately.
27+
28+
- **Flexibility**
29+
Customizable activities and role-based permissions adapt to your team's needs.
30+
31+
---
32+
33+
### <Settings className="inline h-5 w-5 mr-2 text-secondary" /> Key Features
34+
35+
| Feature | Description |
36+
| ------------------------- | ------------------------------------------------ |
37+
| Intuitive Process Editor | Drag & drop start/end nodes, gateways, activities|
38+
| Team Management | Invite members, assign roles, manage access |
39+
| Gamified Task Management | Reward system with points, levels, badges |
40+
| Real-Time Monitoring | Live dashboards for process oversight |
41+
| Custom Activities | Create and integrate your own activities tailored to specific needs or browse our shop for pre-built options. |
42+
43+
---
44+
45+
### <Database className="inline h-5 w-5 mr-2 text-secondary" /> Technical Architecture
46+
47+
<div className="flex flex-row justify-center">
48+
<img src="https://skillicons.dev/icons?i=nextjs,tailwind,supabase,postgres,docker,githubactions&theme=light&perline=15" width="75%" height="auto" alt="Tech Stack" />
49+
</div>
50+
51+
| Component | Details |
52+
| ------------------- | ----------------------------------------------------------------------- |
53+
| **Frontend** | Next.js & Shadcn/ui for a responsive, modern interface |
54+
| **Styling** | Tailwind CSS for utility-first, consistent styling |
55+
| **Backend** | Supabase (PostgreSQL, Auth) + Next.js API routes for server-side logic |
56+
| **Deployment** | Docker Compose for consistent local development and deployment |
57+
| **Real-Time** | Leveraging Supabase’s real-time features for live updates |
58+
| **State Management**| Zustand for efficient client-side state handling |
59+
| **CI/CD** | GitHub Actions for automated deployment and database migrations |
60+
61+
---
62+
63+
### <Eye className="inline h-5 w-5 mr-2 text-secondary" /> Project Background & Vision
64+
65+
Developed by **Merten Dieckmann**, a Master’s student, ProcessFlow was born from the observation that traditional BPM tools often struggle to keep users engaged. Gamification elements motivate users to continuously optimize and maintain transparency in their processes. This project is a continuation of his bachelor thesis, which focused on the integration of gamification in business process management:
66+
67+
<iframe
68+
src="/assets/Bachelorarbeit-Merten-Dieckmann.pdf"
69+
width="100%"
70+
height="800"
71+
title="Merten Dieckmanne Bachelorarbeit"
72+
className="mt-8"
73+
>
74+
Ihr Browser unterstützt keine eingebetteten PDFs.
75+
</iframe>
76+
77+
---
78+
79+
### <BookOpen className="inline h-5 w-5 mr-2 text-secondary" /> Documentation Structure
80+
81+
<div className="grid grid-cols-1 sm:grid-cols-2 gap-8">
82+
<div className="bg-card p-4 rounded-md">
83+
<h3 className="mt-0">Tour</h3>
84+
- [Dashboard](/docs/tour/dashboard)
85+
- [Editor](/docs/tour/editor)
86+
- [Tasks](/docs/tour/tasks)
87+
- [Monitoring](/docs/tour/monitoring)
88+
- [Team](/docs/tour/team)
89+
- [Statistics](/docs/tour/statistics)
90+
- [Settings](/docs/tour/settings)
91+
- [Shop](/docs/tour/shop)
92+
</div>
93+
94+
<div className="bg-card p-4 rounded-md">
95+
<h3 className="mt-0">Available Nodes</h3>
96+
- [Start Node](/docs/available-nodes/start-node)
97+
- [End Node](/docs/available-nodes/end-node)
98+
- [Exclusive Gateway](/docs/available-nodes/exclusive-gateway)
99+
- [Parallel Gateway](/docs/available-nodes/parallel-gateway)
100+
- [Activity](/docs/available-nodes/activity)
101+
</div>
102+
103+
<div className="bg-card p-4 rounded-md">
104+
<h3 className="mt-0">Custom Activities</h3>
105+
- [Creating Custom Activities](/docs/custom-activities/create-custom-activities)
106+
- [How Custom Activities Work](/docs/custom-activities/how-they-work)
107+
</div>
108+
109+
<div className="bg-card p-4 rounded-md">
110+
<h3 className="mt-0">Architecture</h3>
111+
- [Process Engine](/docs/architecture/process-engine)
112+
- [Deployment](/docs/architecture/deployment)
113+
</div>
114+
115+
<div className="bg-card p-4 rounded-md">
116+
<h3 className="mt-0">Additional Resources</h3>
117+
- [Features](/#features)
118+
- [FAQ](/#faq)
119+
- [About Us](/#about)
120+
- [Imprint](/imprint)
121+
</div>
122+
</div>

‎src/content/docs/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"index",
55
"tour",
66
"available-nodes",
7-
"custom-activities"
7+
"custom-activities",
8+
"architecture"
89
]
910
}

0 commit comments

Comments
 (0)