Skip to content

Technical Design Documents

This directory contains Technical Design Documents (TDDs) for the project, which provide detailed technical specifications for specific implementations.

What is a Technical Design Document?

A Technical Design Document (TDD) bridges the gap between high-level architectural decisions (ADRs) and implementation details. While ADRs focus on broad architectural choices, TDDs provide the specific technical details needed to implement a feature, component, or system change.

TDDs serve to:

  • Document detailed technical specifications
  • Provide implementation guidance for developers
  • Define interfaces, data models, and behaviors
  • Establish testing and validation approaches
  • Identify technical risks and mitigation strategies

For more information about TDDs, see the template.

Document List

TDD # Title Status Date Summary
TDD-0001 Icon Management System DRAFT 2025-07-13 A comprehensive system for uploading, searching, and managing icons with support for various formats and color manipulation
TDD-0002 File Storage System DRAFT 2025-07-14 A system for uploading, downloading, and managing files organized in buckets with ownership tracking, reference management, and statistics
TDD-0003 Notification Service DRAFT 2026-02-15 Centralized notification service for email and in-app delivery with template rendering, retry logic, idempotency, and SSE realtime inbox
TDD-0004 Issue Tracking Domain Model DRAFT 2026-02-17 Entities, data model, SQL migrations for Space-scoped catalogs, project configuration, issue keys, custom fields, and type hierarchy
TDD-0005 Issue Tracking Workflows and Boards DRAFT 2026-02-17 Workflow auto-walk algorithm, board columns with primary drop status, LexoRank ordering, and sprint lifecycle
TDD-0006 Issue Tracking Collaboration DRAFT 2026-02-17 Threaded comments, attachments, labels/tags, issue links, checklists, and @mention notifications
TDD-0007 Issue Tracking Audit, Search and Reporting DRAFT 2026-02-17 Activity log, change history, soft delete, search delegation to ai-service, and reporting endpoints

Statuses

  • DRAFT: Initial design document under development
  • REVIEW: Document complete and ready for review
  • APPROVED: Design has been approved but not yet implemented
  • IMPLEMENTED: Design has been fully implemented
  • DEPRECATED: Design is no longer relevant or has been superseded

Creating a New TDD

  1. Copy template.md to create a new file named NNNN-title-with-dashes.md
    • Use the next available number in sequence for NNNN
    • Use lowercase letters and dashes for the title
  2. Fill in the template
  3. Add an entry to the Document List table above
  4. Submit a pull request for review

File Name Convention

TDD files should be named using the following format: NNNN-title-with-dashes.md

  • NNNN is a sequential number with leading zeros (0001, 0002, etc.)
  • title-with-dashes is a brief hyphen-separated title

Example: 0001-authentication-service-implementation.md

Relationship to Other Documents

TDDs work alongside other document types in our project:

  • Architecture Decision Records (ADRs): Define high-level architectural decisions and principles
  • Roadmap Items: Outline strategic product direction and features
  • Technical Design Documents (TDDs): Provide detailed technical specifications for implementation

Each TDD should reference relevant ADRs and roadmap items to maintain alignment with the project's architecture and direction.

Additional Resources