Skip to content

Latest commit

History

38 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

ProjectFlow

Production-ready Project & Task Management Platform

Plan less. Ship more. Together.

🚀 30+ API Endpoints🔐 OAuth + JWT Auth📊 4 Analytics Modules👥 8-Level RBAC📱 PWA Ready⚡ Deno Deploy

Live DemoAPI DocsDenoFreshHonoPrismaMongoDBTypeScriptPWALicensePRs Welcome


Live Demo · API Docs · Report Bug · Request Feature


📊 Project Metrics

MetricValue
API Endpoints30+
Role Levels8 (4 global + 4 per-project)
Authentication Methods3 (Email, Google OAuth, GitHub OAuth)
Analytics Modules4 (Dashboard, Per-Project, Portfolio, Health)
Database Collections8
Frontend Islands44
Routes15
PWA SupportYes
DatabaseMongoDB Atlas
DeploymentDeno Deploy (production)

🎥 Product Walkthrough

ProjectFlow Product Walkthrough

▶️ Click the thumbnail to watch on YouTube (opens in new tab)

🏃 Quick Preview

Jump straight into the live app at projectflow.engsiam.deno.net using any of these demo accounts:

EmailPasswordRoleWhat you can explore
admin@projectflow.devAdmin#12345ADMINFull access — create/delete projects, manage members, all analytics
olivia@projectflow.devOlivia#12345PROJECT_MANAGERCreate projects, invite members, manage tasks
liam@projectflow.devLiam#12345TEAM_MEMBERKanban board, comments, file uploads
noah@projectflow.devNoah#12345VIEWERRead-only: browse projects, tasks, charts, reports

🚀 Why ProjectFlow?

FeatureProjectFlowTypical CRUD App
Authentication & JWT Sessions
Kanban Workflow (Drag & Drop)
Analytics Dashboard
Project Health Intelligence (0–100)
Portfolio Risk Matrix
Workload Balancing
Activity Heatmap (90-day)
Gantt Timeline
OAuth Login (Google + GitHub)
PWA Support
Two-Layer RBAC (8 roles)
PDF Report Export
Predictive Completion Forecasting
Real-time Notifications
Global Command Palette (Cmd+K)
Deno Deploy Production
Swagger/OpenAPI Documentation
CSV Task Export

👨‍💼 Why This Project Stands Out

This repository demonstrates full-stack engineering proficiency across the entire software development lifecycle — from database schema design to production deployment on a serverless edge runtime.

Full-Stack Architecture

The project is split into two independently deployable Deno applications: a Hono REST API and a Fresh + Preact frontend. The backend follows a clean layered architecture (routes → controllers → services → Prisma ORM → MongoDB Atlas) with Zod-validated OpenAPI 3 specs generated directly from route definitions. The frontend uses Fresh's island architecture — interactive Preact components hydrate only where needed, delivering sub-100ms page loads without a bundler.

Production-Grade Authentication

Implementing JWT access/refresh token rotation with bcrypt password hashing, Google & GitHub OAuth 2.0, IP-based rate limiting on auth endpoints, and a two-layer RBAC system (4 global roles × 4 per-project roles = 8 distinct permission levels) demonstrates strong security engineering.

Database Design

The MongoDB schema covers 8 collections with proper indexing, foreign key relationships via Prisma, and a document model designed for the task management domain. The health snapshot collection stores deterministic score computations alongside risk factors, recommendations, and historical trend data — enabling the predictive analytics engine without external services.

Enterprise Analytics Suite

The analytics system spans four levels: workspace dashboard (aggregate KPIs, trends, team workload), per-project analytics (member productivity, task distribution), portfolio intelligence (cross-project health comparison, risk matrix), and project health scoring (0–100 weighted multi-signal algorithm with completion forecasting). This demonstrates the ability to design, implement, and visualize complex data pipelines.

Frontend Engineering

The UI uses CSS custom properties for theming (no Tailwind dependency), responsive grid layouts, SVG-powered progress rings and donut gauges, Recharts for analytics, and a command palette (Cmd+K) for instant project/task/member search. The PDF report feature uses native window.print() with @media print CSS — a zero-dependency approach to document generation.

API Documentation

Every backend route is documented via OpenAPI 3 with Zod validation schemas, exposed through Swagger UI at /docs and machine-readable JSON at /openapi.json. This shows commitment to developer experience and API-first design.

Production Deployment

The application is deployed and live on Deno Deploy's global edge network, with health checks at /health and /readyz, automated Prisma client generation in CI, and a documented cold-start verification pipeline.


Key Features

  • Authentication & Authorization — JWT access/refresh token rotation, email/password signup, Google & GitHub OAuth 2.0
  • Project Management — Create, edit, archive, restore, with start/deadline dates, per-project colors, status workflow (Active / On Hold / Completed / Archived)
  • Task Management — Three-column Kanban (To Do / In Progress / Completed), priority levels, assignees, due dates, labels, threaded comments, file attachments, CSV export
  • Role-Based Access Control — Two-layer RBAC: global roles (ADMIN / PROJECT_MANAGER / TEAM_MEMBER / VIEWER) + per-project roles (OWNER / PROJECT_MANAGER / MEMBER / VIEWER)
  • Analytics Dashboard — Workspace KPIs, task status/priority mix, 30-day trends, per-project analytics, member workload, productivity comparisons
  • Project Health Intelligence — Deterministic 0–100 health score blended from 5 signals (overdue tasks, velocity, deadline proximity, engagement, workload balance); risk classification (ON_TRACK / AT_RISK / CRITICAL); completion forecasting; historical trends
  • Executive Command Center — Dashboard hero with workspace health score ring, project/task/completion/at-risk stats, weekly trend indicator
  • Portfolio Risk Matrix/portfolio page with health score overview, risk matrix table, portfolio insights cards, expandable per-project health intelligence
  • Gantt Timeline — Project Detail Timeline tab with week-header rows, colored bars by status, overdue markers, today line
  • Activity Heatmap — GitHub-style 90-day contribution grid with 5-level intensity coloring
  • Workload Balancer — Team workload analysis with balanced/overloaded/underutilized stats, bar chart, deterministic redistribution recommendations
  • Insights Assistant — Rule-based recommendations engine for overdue tasks, overloaded members, low velocity, unassigned tasks, engagement gaps
  • PDF Report Export — Zero-dependency print-to-PDF via window.print() with @media print CSS, accessible from Project Detail
  • Real-time Notifications — In-app notification center for task assignments, status changes, mentions
  • Global Command Palette — Cmd+K / Ctrl+K search for projects, tasks, and members
  • Mobile-first Responsive UI — Fully responsive layouts, touch-friendly, PWA installable on iOS and Android

🏗️ System Design Overview

The frontend-backend split maps to two independent Deno Deploy projects, each deployable with zero shared infrastructure.

LayerStackKey Design Decision
UIFresh islands + CSS custom propertiesNo bundler — island hydration ships JS only for interactive components
APIHono + Zod + OpenAPIValidation schemas auto-generate OpenAPI 3 docs; invalid requests rejected at route layer
DBMongoDB via Prisma ORMDocument model nests comments/attachments under tasks; typed schema prevents runtime drift
AuthJWT rotation + OAuth 2.0Stateless tokens scale horizontally; OAuth delegates credential security to providers
HealthDeterministic rule engineReproducible, auditable scores — zero external API dependency

Architecture

flowchart TD
A["Fresh Frontend<br/>(Preact Islands)"]
B["Hono API<br/>(Deno 2.x)"]
C["Authentication<br/>(JWT + OAuth)"]
D["Project Service"]
E["Task Service"]
F["Health Engine"]
G["(MongoDB Atlas)"]
A --> B
B --> C
B --> D
B --> E
B --> F
C --> G
D --> G
E --> G
F --> G
Loading

Database Schema

erDiagram
User ||--o{ Project : owns
User ||--o{ ProjectMember : member-of
User ||--o{ Task : assigned
User ||--o{ Comment : writes
User ||--o{ Notification : receives
Project ||--o{ Task : contains
Project ||--o{ ProjectMember : has
Project ||--o{ HealthSnapshot : evaluated
Task ||--o{ Comment : has
Task ||--o{ Attachment : has
Task ||--o{ ActivityLog : generates
User {
string id PK
string email
string name
string password
string role "ADMIN|PROJECT_MANAGER|TEAM_MEMBER|VIEWER"
string avatar
string googleId
string githubId
datetime createdAt
datetime updatedAt
}
Project {
string id PK
string name
string description
string color
string status "ACTIVE|ON_HOLD|COMPLETED|ARCHIVED"
string ownerId FK
datetime startDate
datetime deadline
datetime createdAt
}
Task {
string id PK
string title
string description
string status "TODO|IN_PROGRESS|COMPLETED"
string priority "LOW|MEDIUM|HIGH"
string projectId FK
string assigneeId FK
datetime dueDate
datetime createdAt
int sortOrder
}
ProjectMember {
string id PK
string projectId FK
string userId FK
string role "OWNER|PROJECT_MANAGER|MEMBER|VIEWER"
datetime joinedAt
}
Comment {
string id PK
string content
string taskId FK
string authorId FK
datetime createdAt
}
Notification {
string id PK
string userId FK
string type
string message
string link
boolean read
datetime createdAt
}
Attachment {
string id PK
string filename
string url
string taskId FK
string uploaderId FK
datetime createdAt
}
HealthSnapshot {
string id PK
string projectId FK
int score
string riskLevel "ON_TRACK|AT_RISK|CRITICAL"
json riskFactors
json recommendations
json breakdown
int trend
datetime createdAt
}
ActivityLog {
string id PK
string actorId FK
string projectId FK
string taskId FK
string action
json metadata
datetime createdAt
}
Loading

Screenshots

Authentication

Sign InHome / Landing
Sign InHome / Landing

Dashboard

Executive DashboardAnalytics
Executive DashboardAnalytics Dashboard

Project Management

Projects ListProject DetailKanban Board
Projects ListProject DetailKanban Board

Team & Settings

Team MembersSettings
Team MembersSettings

Tech Stack

Frontend

TechnologyPurpose
Deno Fresh 1.7Web framework with island architecture
Preact 10Lightweight React-compatible rendering
TypeScript 5Type-safe development
CSS Custom PropertiesTheming (dark mode) — no Tailwind dependency
RechartsAnalytics charting library

Backend

TechnologyPurpose
Deno 2.xJavaScript/TypeScript runtime
Hono 4.6Lightweight HTTP framework
Prisma 5.22Type-safe ORM (MongoDB connector)
MongoDB AtlasDocument database
Zod 3.23Schema validation
@hono/zod-openapiOpenAPI 3 spec generation
JWTAccess & refresh token auth
bcryptjsPassword hashing

Infrastructure

ServicePurpose
Deno DeployProduction hosting (backend + frontend)
GitHubSource control & CI
Swagger UIInteractive API explorer

💡 Technical Highlights

Zero-Dependency PDF Reports

PDF Export uses window.print() with @media print CSS — no jsPDF, no Puppeteer, no server-side rendering. Print styles hide navigation, sidebars, and interactive elements while preserving data tables and charts.

Predictive Completion Forecasting

The health engine estimates completion dates using remaining_tasks / 7_day_velocity. On-track probability derives from health score distance to risk thresholds — deterministic, auditable, and explainable.

Island Architecture Performance

Fresh delivers ~45 KB initial JS (vs 200+ KB for typical React SPAs). Each interactive component hydrates independently when it enters the viewport. Complex islands (Kanban, Analytics, Command Palette) don't block page rendering.

CSS-Only Animations

Health score rings, portfolio risk matrix highlights, and dashboard stat cards use CSS custom property transitions and conic-gradient() for SVG-free progress rings — zero animation library.


Project Health Intelligence

Health Intelligence is a deterministic, rule-based analytics engine — no AI, no LLM, no external APIs. It computes a 0–100 health score for every project from five weighted signals drawn from live database data:

SignalWeightWhat it measures
Overdue tasks30Ratio of overdue non-completed tasks
Completion velocity (7-day)20Tasks shipped per week
Deadline proximity25Distance from now to project deadline
Team engagement15Active members in last 7 days
Workload balance10Standard deviation of open tasks across assignees

Risk classification (auto-derived from the score):

  • ON_TRACK — score ≥ 70
  • AT_RISK — score 40–69
  • CRITICAL — score < 40

Predictive outputs:

  • Predicted completion date (remaining tasks / 7-day velocity)
  • On-track probability (0–1 estimate)
  • Score trend with direction indicator
  • Historical sparkline (last 30 snapshots)

Per-project surface:

  • Top 3 risk factors (severity-ranked)
  • Recommended actions (prescriptive next steps)
  • Per-signal score breakdown with progress bars

Workspace overview (dashboard):

  • Average health score across all projects
  • On-track / at-risk / critical counts
  • Top 5 risk + Top 5 healthy projects

API

MethodPathPurpose
GET/api/projects/:projectId/healthScore, risk, factors, recommendations, breakdown, trend
POST/api/projects/:projectId/health/refreshForce recompute + persist snapshot
GET/api/projects/:projectId/health/historyLast 30 snapshots for trend chart
GET/api/dashboard/healthWorkspace summary

🧗 Engineering Challenges & Decisions

Real-time Collaboration Without WebSockets

Problem: Task assignments and mentions need to feel immediate, but WebSocket infrastructure on Deno Deploy's stateless edge is non-trivial. Solution: 15-second polling + optimistic UI updates. Kanban cards update instantly on drag; the PATCH request fires in background. Conflicts resolve via last-write-wins, reconciled on the next poll.

Deterministic Health Scoring

Problem: Health scores must be reproducible, auditable, and explainable — black-box ML won't work. Solution: Five weighted signals (overdue ratio, velocity, deadline proximity, engagement, workload balance) from live DB queries. Formula is transparent, each refresh logs the breakdown, historical snapshots verify trends.

Composable RBAC Middleware

Problem: No authorization framework exists for Hono/Fresh — every route needs global + per-project role checking. Solution: A composable middleware chain: authenticaterequireRole('ADMIN')requireProjectRole('OWNER'). Each middleware resolves context from JWT payload + Prisma queries, returning 401/403 immediately on failure.

MongoDB Relations Without JOINs

Problem: MongoDB has no JOINs across 8 interrelated collections. Solution: Prisma's MongoDB connector provides relational queries over a document database. Indexes on foreign key fields keep aggregation pipelines under 100ms. Embedded comments/attachments reduce collection scans.

CSV Export at the Edge

Problem: Deno Deploy has no filesystem — fs.writeFileSync doesn't exist. Solution: Stream CSV rows using Deno's TextEncoder + Response body streaming. Frontend receives the stream as a Blob and triggers download via URL.createObjectURL.


Live Deployment

ServiceURLPurpose
Frontendhttps://projectflow.engsiam.deno.netUser-facing web application
Backend APIhttps://projectflow-backend.engsiam.deno.netREST API
Swagger UIhttps://projectflow-backend.engsiam.deno.net/docsInteractive API documentation
OpenAPI JSONhttps://projectflow-backend.engsiam.deno.net/openapi.jsonMachine-readable spec
Health Checkhttps://projectflow-backend.engsiam.deno.net/healthLiveness probe
Readinesshttps://projectflow-backend.engsiam.deno.net/readyzDB-backed readiness probe

Quick Start

Prerequisites

ToolVersionRequired For
Deno2.0+Backend and frontend runtime
MongoDB6.0+Database (local or Atlas free tier)
GitlatestCloning the repository

Setup

# 1. Clone
git clone https://github.com/engsiam/ProjectFlow-Task-Management-APP.git
cd ProjectFlow-Task-Management-APP
# 2. Start MongoDB (Docker)
docker run -d --name projectflow-mongo -p 27017:27017 mongo:7
# 3. Backendcd backend
cp .env.example .env # edit DATABASE_URL if needed
deno task prisma:push # apply schema to MongoDB
deno task seed # (optional) load demo data
deno task dev # starts at http://localhost:8000# 4. Frontend (new terminal)cd ../frontend
cp .env.example .env # set API_BASE_URL=http://localhost:8000/api
deno task dev # starts at http://localhost:8001

Open http://localhost:8001 and sign in with the seeded demo accounts.

Environment Variables

Backend (backend/.env)

# RequiredDATABASE_URL="mongodb://localhost:27017/projectflow"JWT_ACCESS_SECRET="<32+ random bytes>"JWT_REFRESH_SECRET="<32+ random bytes>"# OptionalPORT=8000NODE_ENV=developmentFRONTEND_URL=http://localhost:8001OAUTH_REDIRECT_URL=http://localhost:8000/api/auth# OAuthGOOGLE_CLIENT_ID=GOOGLE_CLIENT_SECRET=GITHUB_CLIENT_ID=GITHUB_CLIENT_SECRET=# StorageUPLOAD_DIR=uploadsSTORAGE_BACKEND=local

Frontend (frontend/.env)

API_BASE_URL=http://localhost:8000/api

Role-Based Access Control

Global Roles

RoleCreate ProjectManage MembersManage RolesDelete Anything
ADMIN
PROJECT_MANAGER✓ (own projects)
TEAM_MEMBER
VIEWER

Per-Project Roles

RoleEdit ProjectInviteCreate TasksAssignDelete Tasks
OWNER
PROJECT_MANAGER
MEMBER✓ (assigned only)
VIEWER

Only ADMIN can delete projects, archive projects, or remove members.


API Endpoints

All endpoints live under /api. Full documentation is available at /docs (Swagger UI) and /openapi.json (raw spec).

Auth (/api/auth)

MethodPathDescription
POST/api/auth/signupCreate account
POST/api/auth/loginEmail + password login
POST/api/auth/refreshRotate access token
POST/api/auth/logoutInvalidate session
GET/api/auth/meCurrent user profile
GET/api/auth/googleGoogle OAuth flow
GET/api/auth/githubGitHub OAuth flow

Users (/api/users)

MethodPathDescription
PATCH/api/users/meUpdate own profile
GET/api/users/searchSearch users for invites
GET/api/users/:userIdPublic profile
PATCH/api/users/:userId/roleAdmin-only role change

Projects (/api/projects)

MethodPathDescription
GET/api/projectsList user's projects
POST/api/projectsCreate project
GET/api/projects/:idProject detail
PATCH/api/projects/:idEdit project
POST/api/projects/:id/archiveArchive project
DELETE/api/projects/:idAdmin-only delete
GET/api/projects/:id/membersList members
GET/api/projects/:id/activityActivity feed
GET/api/projects/:id/export/tasks.csvCSV export

Tasks (/api/projects/:id/tasks)

MethodPathDescription
GET/api/projects/:id/tasksList tasks (paged, filtered, sorted)
POST/api/projects/:id/tasksCreate task
GET/api/tasks/:idTask detail
PATCH/api/tasks/:idUpdate task
POST/api/tasks/:id/moveChange status
DELETE/api/tasks/:idAdmin-only delete

Comments, Notifications, Uploads

MethodPathDescription
POST/api/tasks/:id/commentsAdd comment
GET/api/tasks/:id/commentsList comments
GET/api/notificationsList notifications
PATCH/api/notifications/:idMark notification read
POST/api/uploads/avatarUpload avatar
POST/api/projects/:id/tasks/:taskId/attachmentsUpload attachment

System

MethodPathDescription
GET/healthLiveness probe
GET/readyzDB-backed readiness probe
GET/api/dashboardPersonal dashboard
GET/api/dashboard/portfolioPortfolio & executive overview
GET/api/dashboard/healthWorkspace health summary
GET/api/analytics/dashboardWorkspace analytics
GET/api/analytics/project/:projectIdPer-project analytics KPIs

Deployment

ProjectFlow is production-verified for Deno Deploy.

One-Click Deploy

  1. Push this repository to GitHub.

  2. In Deno Deploy, create a new project from your repository.

  3. Configure:

    SettingValue
    App Directorybackend
    Entrypointsrc/server.ts
    Build Commanddeno task build:deploy
    Health Check Path/readyz
  4. Add environment variables:

    • DATABASE_URL — MongoDB Atlas connection string
    • JWT_ACCESS_SECRET — 32+ random bytes
    • JWT_REFRESH_SECRET — 32+ random bytes
    • FRONTEND_URL — your deployed frontend URL
  5. Deploy.

Pre-flight Checklist

  • deno task prisma:generate runs locally
  • Build Command set to deno task build:deploy
  • Health Check Path set to /readyz
  • DATABASE_URL points to MongoDB Atlas
  • FRONTEND_URL matches deployed frontend origin
  • JWT secrets are strong random values

Development Scripts

Backend

TaskDescription
deno task devWatch mode with hot reload
deno task startProduction-style start
deno task prisma:generateRegenerate Prisma client
deno task prisma:pushPush schema to MongoDB
deno task prisma:studioOpen Prisma Studio
deno task seedSeed demo data
deno task typecheckType-check backend

Frontend

TaskDescription
deno task devFresh dev server on port 8001
deno task startBuild & start production server
deno task buildPre-render static pages
deno task checkType-check (Fresh + Preact)

Quality

deno task typecheck # Type-check
deno fmt --check # Format check
deno lint # Lint

Project Structure

ProjectFlow-Task-Management-APP/
├── backend/ # Deno + Hono + Prisma API
│ ├── src/
│ │ ├── config/ # Environment, CORS
│ │ ├── controllers/ # Route handlers
│ │ ├── middleware/ # Auth, RBAC, rate-limit, error
│ │ ├── prisma/ # Prisma client singleton
│ │ ├── routes/ # OpenAPI route definitions
│ │ ├── services/ # Business logic
│ │ ├── types/ # Domain enums, context types
│ │ ├── utils/ # Cache, errors, response, CSV
│ │ ├── app.ts # Hono app factory
│ │ └── server.ts # Entrypoint
│ ├── prisma/
│ │ ├── schema.prisma # MongoDB schema
│ │ └── seed.ts # Demo data seeder
│ ├── scripts/
│ ├── deno.json
│ └── README.md
│
├── frontend/ # Fresh + Preact UI
│ ├── islands/ # Interactive client components
│ ├── components/ # Server-rendered components
│ ├── lib/ # API client, auth, RBAC
│ ├── routes/ # Fresh pages
│ ├── static/ # CSS, assets
│ ├── dev.ts # Dev entrypoint
│ ├── main.ts # Prod entrypoint
│ ├── fresh.config.ts
│ └── README.md
│
├── design/ # Mockups, brand assets
└── README.md # You are here

Contributing

  1. Fork the repository
  2. Branch from main: git checkout -b feat/feature-name
  3. Commit your changes using Conventional Commits
  4. Push: git push origin feat/feature-name
  5. Open a Pull Request

Ensure your PR passes:

  • deno task typecheck
  • deno fmt --check
  • deno lint

License

This project is licensed under the MIT License — see the LICENSE file for details.


Built with Deno, Fresh, Hono, Prisma, and MongoDB

If ProjectFlow helped you ship faster, give us a star!


Copyright © 2026 ProjectFlow. MIT Licensed.

About

ProjectFlow – Full Stack Task Management System built with Deno Fresh, Hono, MongoDB, JWT Authentication, PWA, Project & Team Collaboration Features

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages