dgg-pm: Discord-Native Task Management Platform

A self-hosted, zero-signup Discord-native project management platform built to eliminate context-switching by embedding task workflows directly into Discord text channels, threads, and direct messages.

---

📚 Documentation & Wiki

Detailed guides, command references, and architecture documents are available in the DGG-PM Wiki:

• 🚀 Workflow & Quickstart Guide: End-to-end setup and zero-command daily workflows.
• ⌨️ Slash Commands Reference (/pm): Complete parameter and permission breakdown.
• 👥 Teams & Authorization Matrix: Discord-native role rosters and self-healing leads.
• 📌 Forum Channels & Interactive Hubs: Tag auto-provisioning and pinned control centers.

---

Key Features

• Unified /pm Slash Command Group: Single isolated namespace eliminating server command clutter and bot collisions.
• Pinned Forum Control Hubs: Permanent interactive dashboards (📌 📊 Control Hub) pinned in project forums for zero-command task creation and management.
• Discord-Native Squad Rosters: Functional teams are mapped directly to live Discord server roles with automatic self-healing for orphaned leads.
• Dedicated Task Channels & Threads: Tasks automatically spawn dedicated discussion threads with real-time interactive Action Cards ([ ⏳ To Do ], [ 🟡 In Progress ], [ 🟢 Complete ], [ ⚡ Priority ], [ 👤 Reassign ]).
• Human-Friendly Short IDs & Autocomplete: Sequential project-prefixed IDs (e.g. INF-1, PRJ-42) with atomic SQL counter generation and channel-scoped autocomplete.
• Audit History & Optimistic Concurrency Control (CAS): Complete lifecycle history in task_history table and version-checked updates preventing lost update races.
• Postgres-Native Transactional Outbox: At-least-once reminder and notification dispatch with FOR UPDATE SKIP LOCKED, unique idempotency_key deduplication, and dynamic Discord 429 Retry-After backoff.
• RFC 5545 & Microsoft Graph Schema Portability: Native mapping to VTODO and todoTask data standards from Day 1 for future calendar integration.

---

System Architecture

+-----------------------------------------------------------------------------------+
|                                DRIVING ADAPTERS                                   |
|                                                                                   |
|   +------------------------------------+   +----------------------------------+   |
|   |       Discord Bot Adapter          |   |        FastAPI Service Engine    |   |
|   |  (discord.py: Slash / UI / Modals) |   |    (/healthz, /metrics, schemas) |   |
|   +-----------------+------------------+   +----------------+-----------------+   |
+---------------------|---------------------------------------|---------------------+
                      |                                       |
                      v                                       v
+-----------------------------------------------------------------------------------+
|                            APPLICATION / USE CASE LAYER                           |
|                                                                                   |
|   - TaskService: CreateTask, UpdateStatus (CAS), AddNote, FilterTasks, Autocomplete|
|   - ProjectService: CreateProject, BindChannel, GenerateShortId, Archive/Restore   |
|   - TeamService: CreateTeam, SyncDiscordRoles                                     |
|   - OutboxService: EnqueueEvent, ScheduleTieredReminders, CancelTaskReminders     |
+-------------------------------------+---------------------------------------------+
                                      |
                                      v
+-----------------------------------------------------------------------------------+
|                              DOMAIN MODEL (CORE)                                  |
|                                                                                   |
|   - Entities: Task, TaskHistory, Project, Team, OutboxEvent                       |
|   - Value Objects: TaskStatus, PriorityLevel, ShortTaskId, IsoTimestamp            |
|   - State Machine: notStarted -> inProgress -> completed (with CAS validation)    |
|   - Schema Standard Mappings: RFC 5545 (VTODO) / MS Graph (todoTask)              |
+-------------------------------------+---------------------------------------------+
                                      |
                                      v
+-----------------------------------------------------------------------------------+
|                                DRIVEN ADAPTERS                                    |
|                                                                                   |
|   +------------------------------------+   +----------------------------------+   |
|   |    PostgreSQL Relational Repo      |   |  Transactional Outbox Dispatcher |   |
|   |   (SQLAlchemy Async + Alembic)     |   |   (Async Worker SKIP LOCKED)     |   |
|   +------------------------------------+   +----------------------------------+   |
+-----------------------------------------------------------------------------------+

---

Discord Slash Commands

Slash Command	Required Permission	Description
/project-create	Manage Server	Instantiate a top-level project container and bind channel
/project-assign	Manage Server	Map a functional team to a project with timeline
/project-list	Standard Member	List all active projects in the server
/project-archive	Manage Server	Archive project and its active tasks
/project-unarchive	Manage Server	Restore archived project
/team-create	Manage Server	Define a functional team mapped to a Discord server role
/team-assign	Manage Server	Assign a member to a team with domain role (lead / member)
/team-list	Standard Member	List all configured server teams
/task-create	Standard Member	Create project task with embed card and discussion thread
/task-standalone	Standard Member	Create ad-hoc task independent of project containers
/task-status	Standard Member	Update execution status (with autocomplete)
/task-history	Standard Member	View full chronological audit trail of a task
/task-list	Standard Member	Filter and browse active tasks with interactive pagination
/task-archive	Standard Member	Soft-delete an individual task
/task-unarchive	Standard Member	Restore an archived task
/help-pm	Standard Member	Display bot guides and operational documentation

---

Quickstart & Setup

1. Prerequisites

• Python 3.12+
• PostgreSQL 16+ (or Docker)
• Discord Bot Application Token (Discord Developer Portal)

2. Environment Configuration

Copy .env.example to .env and fill in your Discord Bot credentials:

cp .env.example .env

Edit .env:

DISCORD_BOT_TOKEN=your_token_here
DISCORD_CLIENT_ID=your_client_id_here
DISCORD_GUILD_ID=your_test_guild_id   # Optional: faster command syncing in dev
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/dgg_pm

3. Required Discord Bot Permissions & Intents

When inviting the bot to your Discord server, ensure the following permissions are granted:

• Bot Permissions: Manage Channels (for auto-tagging Forum channels), Manage Threads, View Channels, Send Messages, Send Messages in Threads, Create Public Threads, Manage Messages, Embed Links, Read Message History.
• Privileged Gateway Intents: Guilds, GuildMembers. (Note: MessageContent is explicitly NOT required).

4. Running with Docker Compose

docker-compose up --build

5. Running with devenv (Nix)

With devenv installed:

# Enter the devenv developer shell (installs Python 3.12, dependencies via uv, PostgreSQL 16, tools)
devenv shell

# Start background services (PostgreSQL & app)
devenv up

# Run helper scripts inside the devenv shell
run-tests    # Execute pytest test suite
run-app      # Launch platform
db-init      # Initialize database schema
db-clear     # Wipe/truncate PostgreSQL database tables
db-reset     # Wipe database tables and re-seed test data
db-shell     # Connect to local PostgreSQL
format       # Autoformat with ruff
lint         # Lint check with ruff

6. Running Locally (Standard Python)

pip install -e ".[dev]"
pytest
python src/main.py