Files

5.6 KiB

DECISIONS LOG

Version: 1.0 Date: 2026-09-27

Purpose:

This document records all significant architecture, platform, technology and delivery decisions made within the DemoTel initiative.

The objective is to avoid repeatedly revisiting previously agreed decisions and to provide future team members and AI assistants with historical context.


ADR-001

Title

Gitea Is The Source Of Truth

Status

Approved

Date

2026-09

Decision

All source code, architecture artifacts, standards, templates and project documentation shall be stored in Gitea.

Reason

Provides:

  • Version Control
  • Audit Trail
  • Branching
  • Collaboration
  • Central Knowledge Repository

Implications

Documents should not be maintained as isolated local copies.


ADR-002

Title

MongoDB Is The Primary Operational Database

Status

Approved

Date

2026-09

Decision

MongoDB will be used as the primary operational datastore for DemoTel accelerator applications.

Reason

Provides:

  • Flexible Schema
  • Rapid Development
  • Easy Integration With n8n
  • Suitable For AI Metadata Storage

Planned Usage

  • Customer Data
  • Account Data
  • Product Data
  • Metadata
  • Agent Execution Logs
  • Conversation History

ADR-003

Title

Qdrant Is The Vector Database

Status

Approved

Date

2026-09

Decision

Qdrant will be used for semantic search and RAG capabilities.

Reason

Provides:

  • Open Source
  • Easy Deployment
  • Strong Vector Search
  • Good n8n Integration

Usage

  • Embeddings
  • Semantic Search
  • Knowledge Retrieval

ADR-004

Title

n8n Is The Orchestration Platform

Status

Approved

Date

2026-09

Decision

n8n will act as the primary workflow orchestration platform.

Reason

Provides:

  • Low Code Automation
  • AI Integration
  • Workflow Management
  • Rapid Prototyping

Responsibilities

  • Knowledge Ingestion
  • AI Workflows
  • System Integration
  • Data Movement

ADR-005

Title

Documentation First Delivery

Status

Approved

Date

2026-09

Decision

Business and architecture documents should be created before implementation begins.

Reason

Ensures:

  • Shared Understanding
  • Design Consistency
  • Better AI Generation Results
  • Improved Traceability

Preferred Sequence

Requirements ↓ Architecture ↓ Design ↓ Implementation


ADR-006

Title

React Is The Enterprise UI Platform

Status

Approved

Date

2026-09

Decision

The AI Workspace frontend will be built using React.

Technology Stack

  • React
  • TypeScript
  • TailwindCSS
  • ShadCN UI

Reason

Provides:

  • Modern User Experience
  • Component Reuse
  • Strong Ecosystem
  • Enterprise Adoption

ADR-007

Title

No FastAPI In Phase 1

Status

Approved

Date

2026-09

Decision

Phase 1 will use direct integration between React and n8n.

Architecture

React ↓ n8n ↓ Services

Reason

Reduces:

  • Complexity
  • Development Time
  • Operational Overhead

Review Trigger

Revisit when custom business APIs or agent orchestration become complex.


ADR-008

Title

Container First Deployment

Status

Approved

Date

2026-09

Decision

All applications should be packaged as Docker containers.

Reason

Provides:

  • Portability
  • Repeatability
  • Easy Deployment
  • Consistent Configuration

Target Platform

Docker Compose

Future Consideration

Kubernetes if scale requires it.


ADR-009

Title

Traefik As Standard Reverse Proxy

Status

Approved

Date

2026-09

Decision

Traefik will front all externally exposed services.

Responsibilities

  • SSL
  • Routing
  • Domain Mapping

Reason

Already deployed and operational.


ADR-010

Title

Knowledge Repository Strategy

Status

Approved

Date

2026-09

Decision

Use demotel-docs repository as the central knowledge repository.

Reason

Single source for:

  • Context
  • Standards
  • Templates
  • Architecture
  • Roadmaps

Repository Structure

00-context 01-business 02-standards 03-architecture 04-templates 05-domains 06-projects


ADR-011

Title

Maintain Persistent Project Context

Status

Approved

Date

2026-09

Decision

A master context document shall be maintained.

Document

DEMOTEL_MASTER_CONTEXT.md

Purpose

Provide onboarding context for:

  • New AI Assistants
  • New Team Members
  • New Devices
  • New Development Environments

ADR-012

Title

Traceability Is Mandatory

Status

Approved

Date

2026-09

Decision

All generated artifacts should support traceability.

Target Model

Requirement ↓ Epic ↓ Feature ↓ User Story ↓ Design ↓ Code ↓ Test ↓ Deployment

Reason

Supports:

  • Governance
  • Auditability
  • Impact Analysis
  • AI Explainability

ADR-013

Title

Business Domain Driven Architecture

Status

Approved

Date

2026-09

Decision

Applications should be aligned to business domains.

Current Domains

  • CRM
  • Product Catalog
  • OMS
  • Billing
  • Inventory
  • Provisioning

Reason

Supports:

  • Separation Of Concerns
  • Independent Deployment
  • Scalability

ADR-014

Title

AI Workspace Is The Strategic Product

Status

Approved

Date

2026-09

Decision

The long-term focus is the creation of the DemoTel AI Workspace.

Capabilities

  • Chat
  • Knowledge Search
  • Document Generation
  • Agent Management
  • Traceability
  • SDLC Automation

Reason

Acts as the central interface for all future platform capabilities.


FUTURE DECISIONS

Add new ADRs sequentially.

Example:

ADR-015 ADR-016 ADR-017

Do not modify historical decisions unless the decision has been formally superseded.

If a decision changes:

Original ADR: Status = Superseded

New ADR: Status = Approved


DECISION REVIEW SCHEDULE

Review Period

Every major release.

Review Areas

  • Architecture
  • Security
  • AI Strategy
  • Knowledge Platform
  • Deployment Model
  • Technology Choices

END OF DOCUMENT