The Problem

Teams needing project management capabilities currently face a choice between SaaS platforms that lock data behind proprietary APIs and open-source alternatives that require significant engineering effort to self-host. The SaaS route means data resides on third-party infrastructure with limited export control; the open-source route typically demands DevOps expertise most teams don't have. This repo addresses that gap by providing a self-hosted platform purpose-built for teams that want transparency and data ownership without running their own infrastructure from scratch.

What This Does

TaskView is a full-featured project management platform with task tracking, kanban boards, sprint planning, time tracking, analytics, and role-based permissions. The codebase is organized around a clear separation between the API server and web interface:

  • api/ (506 files) - The Express-based backend server written in TypeScript. This is the control plane handling authentication, business logic, and data persistence.
  • web/ (530 files) - The Vue.js frontend interface with Tailwind CSS styling, providing the user experience.
  • taskview-packages/ (185 files) - Additional packages including a capacitor bridge for mobile integration and a taskview-api example.
  • web__old/ (473 files) - Appears to be a legacy version of the web interface.

The API entry point is api/server.ts which initializes an Express server, connects to PostgreSQL, and starts listening. Request flow goes through api/src/App.ts which sets up middleware (CORS, error handling, user validation) before routes are registered via api/src/routes/index.ts. Core business logic lives in api/src/core/ - files like EventBus.ts, Dispatcher.ts, JobQueue.ts, and FetchTasksQueryBuilder.ts handle the application's internal messaging, task processing, and job scheduling. Permissions logic is centralized in GoalPermissionsChecker.ts, GoalPermissionsFetcher.ts, and GoalPermissionsRepository.ts.

The API touches PostgreSQL for data persistence and Centrifugo for real-time updates (visible in the dev-container docker-compose configs). The web interface communicates with the API via REST endpoints, and the system uses migrations under api/src/migrations/ for schema management.

How It Is Wired

Execution starts at api/server.ts - this is the sole entry point for the backend. From there:

  1. api/src/App.ts configures the Express application with middlewares in this order: CORS (api/src/middlewares/cors.ts), error handler (api/src/middlewares/error-handler.ts), user middleware (api/src/middlewares/app-user-middleware.ts), and org membership check (api/src/middlewares/is-org-member.ts).
  2. Routes are registered from api/src/routes/index.ts - these define the API endpoints for tasks, projects, users, permissions, etc.
  3. Core business logic flows through EventBus.ts for event propagation and Dispatcher.ts for request dispatching.
  4. JobQueue.ts manages background job processing - likely for tasks like notifications, analytics computation, or email sending.
  5. Permissions are checked via the GoalPermissions* suite before any write operation proceeds.

The widest blast radius sits in the permissions layer - GoalPermissionsChecker, GoalPermissionsFetcher, and GoalPermissionsRepository all gate writes to tasks, goals, and projects. A change to permission logic touches three files and potentially affects every API endpoint that modifies state.

Outside the process, the API connects to PostgreSQL (migrations in api/src/migrations/taskview/) and Centrifugo for real-time features (config in api/dev-containers-test/centrifugo/config.json). The web frontend at web/ consumes these endpoints and renders the UI.

How To Use It

Setup

The project uses pnpm as package manager (inferred from api/package.json and root package.json). To install:

pnpm install

The API requires environment configuration - copy api/.env.example to api/.env and set the required variables. Key vars likely include database connection strings and Centrifugo keys based on the config files present.

Database

Migrations are under api/src/migrations/taskview/. To run migrations:

pnpm run migrate

(or whatever the script is named in api/package.json - verify the available scripts).

Running the API

pnpm start

or

node api/dist/server.js

The server starts on the port defined in api/.env (default likely 3000 or 5000 based on typical Express setups).

Running the Web UI

pnpm --filter web run dev

or from the root:

pnpm run dev

(verify available scripts in root package.json).

Docker

Dockerfiles exist at api/dockerfile and api/postgresql/dockerfile. A docker-compose file is at api/dev-containers-test/docker-compose.yml. The repo appears designed for docker-based deployment given the number of docker config files present.

Real-World Use

A software team wanting to replace Jira or Asana with self-hosted infrastructure can deploy this repo in about 30-45 minutes. The team installs dependencies, runs the PostgreSQL migration to create the schema, sets API_URL and auth config in api/.env, then starts the server. The Vue frontend is accessible at the configured URL. Team members authenticate (likely via email/password or SSO based on the sso.png screenshot in the README), create projects, and start tracking tasks through the kanban board or list views.

The taskview-packages/capacitor-widget-bridge/ suggests there's also a mobile wrapper capability, though this would require additional native configuration for iOS/Android deployment.

Code Health & Issues

Measured Analysis:

  • 84 test files found - test suite exists but coverage profile is unknown
  • 48 doc files found - documentation present in docs/ directory
  • TypeScript: 748 files - strong type coverage across the API
  • SQL: 147 files - substantial database schema and migration code
  • Vue: 359 files - significant frontend codebase

No structural red flags detected - tests, CI, license, and lockfile are all present where expected.

SDLC Observations:

  • web__old/ directory suggests an active migration or refactor in progress - worth confirming whether this is deprecated code or an alternate build
  • api/src/migrations/ contains SQL migration files - the presence of restore/upgrade paths (restore-permissions.sql) suggests the migration system has been used in production
  • The Source-Available license (per the README badge) means this is source-available but not fully open source - commercial use may require additional terms

The Bottom Line

This is a competent self-hosted task management platform that hits the sweet spot for teams wanting data control without building from scratch. The TypeScript-heavy API (748 files) provides strong type safety, the Vue frontend is fully featured, and Docker configs indicate reasonable deployment ergonomics. The permissions layer is the architectural focal point - it's the thinnest point for modification but also the most impactful. Teams that need SSO, fine-grained role controls, and real-time collaboration will find this viable; teams needing purely MIT-licensed code or zero-config cloud deployment should look elsewhere.