TaskiMate — Enterprise-Grade Agile Dashboard & Project Workspace

TaskiMate is a premium, real-time software development ticket dashboard and project workspace modeled after Atlassian Jira. It pairs a responsive, high-fidelity React frontend with a high-velocity FastAPI backend.

Designed for high-scale collaborative teams, TaskiMate features strict schema validations, role-based access control, server-side Google OAuth, Redis-backed WebSocket scaling, and MongoDB transactional safety.

---

🚀 Key Architecture Highlights

TaskiMate is built upon several modern architectural foundations:

1. GraphQL API Layer: Transitioned core data retrieval from REST to a nested GraphQL query layer using Strawberry GraphQL and FastAPI. This allows the client to load complex boards, tickets, and activities in a single roundtrip while completely eliminating over-fetching.

   [!NOTE] For a full design review of this decision, see rest_to_graphql.md.

2. MongoDB ACID Transactions: Operations (such as status updates or issue creation) write atomically across multiple collections (e.g., tickets, activities) using client sessions. If database operations fail, the state rolls back to maintain database consistency.
3. Google OAuth 2.0 Flow: Replaced manual OTP input with a secure, server-side authorization code flow redirecting users directly to Google's consent portal and issuing localized JWT tokens.
4. Scale-Out WebSockets: Distributed updates are synchronized across multiple parallel server instances using Redis Pub/Sub to broadcast real-time events uniformly.
5. Role-Based Access Control (RBAC): Access is partitioned into Admin, Member, and Viewer roles with corresponding UI visibility toggles and backend endpoint guards.
6. Brand-Aligned Dynamic Theme: On startup, a pure-Python PNG chunk decoder reads logo.png, crops it to its content box, and extracts the dominant color to override Tailwind v4 theme variables, aligning the site color scheme automatically.

---

🎨 Core Product Features

1. Collapsible Project Navigation

• Multi-pane dashboard layout managed in Layout.tsx featuring a collapsible sidebar and top-nav.
• Consistent horizontal dividers dynamically matching header offsets (aligned at h-20).
• Deep-linked view states managed through standard React Router parameters (?tab=...).

2. Multi-Tab Workspace Views

• Kanban Board: Drag-and-drop workflow lanes supporting text search filtering and assignee avatar selection.
• Sprint Backlog: Segmented view separating sprint lists from the product backlog, featuring inline quick-ticket creation inputs.
• Roadmap: Gantt-style timeline visualization tracking issue schedules chronologically.
• Confluence Wiki Pages: Relational documentation center for workspace notes, page creation, and markdown viewing.
• Issues Explorer: Table spreadsheet view with sorting, text searching, and data export simulations.
• Project Settings: Operational dashboard display showing issue status distribution graphs and registered team directories.

3. Sliding Issue Drawer & Inline Editing

• Clicking any issue opens a drawer from the right side of the viewport (IssueDetailDrawer.tsx).
• Supports inline text descriptions (saving/canceling on focus changes), real-time status transitions, reporter directories, and ticket-specific activity feeds.

---

🛠️ Technology Stack

Backend

• FastAPI — High-performance Python web framework.
• Strawberry GraphQL — Python library for typed schemas at /graphql (configured in graphql_schema.py).
• MongoDB — NoSQL database using replica sessions for ACID compliance.
• Redis — Pub/sub messaging database for WebSocket cluster syncing.
• Pydantic v2 — Structural schema verification.

Frontend

• React 19 & TypeScript — Component layers.
• Vite — Build tool and dev server.
• Tailwind CSS v4 — Utility classes with HSL tokens.

---

📦 Setup and Installation

Prerequisites

• Node.js (v18+)
• Python (v3.10+)
• Redis Server
• MongoDB (Replica Set recommended for transactions, fallback active for standalone)

Local Development Setup

1. Backend Server

1. Navigate to the backend directory:

   cd BACKEND

2. Initialize virtual environment and install dependencies:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   source .venv/bin/activate
   
   pip install -r requirements.txt

3. Configure environment variables in a:\BACKEND\TaskiMate\.env (see template below).
4. Run the development server with reload flags:

   uvicorn main:app --reload --port 8000

2. Frontend App

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Run the Vite development server:

   npm run dev

4. Open the application at http://localhost:5173/.

---

⚙️ Environment Variables

Backend Configuration (.env)

DATABASE_URL=mongodb://localhost:27017/ticket_dashboard
JWT_SECRET=your_jwt_signing_key_here
FRONTEND_URL=http://localhost:5173
VITE_GOOGLE_CLIENT_ID=your_google_oauth_client_id
GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback
REDIS_HOST=localhost
REDIS_PORT=6379
SUPER_TOGGLE_PWD=admin123

Frontend Configuration (frontend/.env)

VITE_API_URL=http://localhost:8000
VITE_GOOGLE_CLIENT_ID=your_google_oauth_client_id

---

📡 API Routing Architecture

GraphQL Endpoint

• POST /graphql — Strawberry GraphQL endpoint serving all core queries, nested lists, and issue mutations.

REST Support Endpoints

• Authentication:
  • GET /auth/google/callback — Handles Google OAuth token exchanging.
  • GET /auth/me — Fetches current user session info.
• Administrative Utilities:
  • POST /api/super-toggle — Manages super mode switches.
  • PATCH /api/users/{id}/role — Configures RBAC mappings for users.

Real-Time Connections

• WS /ws/activity — Bidirectional WebSockets connecting frontend users to horizontal Redis Pub/Sub channels.