mcp-software-planning

Black-Tortoise is an enterprise-grade starter kit pursuing "extreme decoupling" and "strong consistency." We follow the Occam's Razor principle: do not multiply entities beyond necessity. Every line of code must justify its existence, and every architectural layer must strictly observe its boundaries.

---

0. Design Guide Index

• [Workspace Capability Architecture Constitution (Index)](docs/INDEX.md)
• Core Modules

- [Shell](src/app/shell/README.md)

- [Workspace](src/app/workspace/README.md)

- [Workflows](src/app/workflows/README.md)

- [Eventing](src/app/eventing/README.md)

- [Integration](src/app/integration/README.md)

- [Shared (Shared Kernel)](src/app/shared/README.md)

- [Account](src/app/account/README.md)

- [Capabilitys Overview](src/app/capabilitys/README.md)

• Capability Guides

- [Acceptance](src/app/capabilitys/acceptance/README.md)

- [Audit](src/app/capabilitys/audit/README.md)

- [Calendar](src/app/capabilitys/calendar/README.md)

- [Daily](src/app/capabilitys/daily/README.md)

- [Documents](src/app/capabilitys/documents/README.md)

- [Finance](src/app/capabilitys/finance/README.md)

- [Intelligence](src/app/capabilitys/intelligence/README.md)

- [Issues](src/app/capabilitys/issues/README.md)

- [Members](src/app/capabilitys/members/README.md)

- [Overview](src/app/capabilitys/overview/README.md)

- [Permissions](src/app/capabilitys/permissions/README.md)

- [Quality Control](src/app/capabilitys/quality-control/README.md)

- [Settings](src/app/capabilitys/settings/README.md)

- [Tasks](src/app/capabilitys/tasks/README.md)

1. Core Contexts

• [Account Module](src/app/account/README.md) - Manages User, Organization, and authorization.
• [Workspace Context](src/app/workspace/README.md) - Logical boundary for all business capabilities.

2. Capabilities

• [Capabilitys Overview](src/app/capabilitys/README.md) - Includes 12 independent modules such as Tasks, Documents, QC, Calendar, etc.

3. Foundations

• [Architecture Governance](.github/instructions/61-architectural-governance-copilot-instructions.md) - CI-level DDD and Event-Sourcing enforcement mechanism.
• [Audit Capability](docs/AUDIT_CAPABILITY_DEV_GUIDE.md) - Audit capability development guide and quality standards.
• [Eventing System](src/app/eventing/README.md) - Purely reactive event bus and storage design.

---

1. Strict Layered Boundaries (DDD Layers)

• Presentation: Pure view and Signals data binding. EventStore access is forbidden.
• Application: Use case orchestration and state management (NgRx Signals Stores).
• Domain: Pure business logic, entities, and value objects. Zero framework dependencies.
• Infrastructure: Technical implementation (Firebase, HTTP, external SDKs).

2. Event-Driven Communication

• Inter-module communication is only allowed via events.
• Follow Append-Before-Publish: persist to EventStore first, then publish to EventBus.

3. Zero-Config Backend

• Seamless initialization based on GCP ADC and Firebase.
• Supports AI-driven automated audit and architecture guard.

4. Pure Reactive & Modern Control Flow

• Pure Reactive: The system fully adopts Angular Signals. Observables are limited to the Infrastructure layer and converted to Signals at the Application boundary. Achieves zone-less change detection for better performance and predictability.
• Modern Control Flow: Completely abandons legacy structural directives (ngIf, ngFor). Uses Angular 18/20 standard @if, @for, @switch, and @defer syntax for intuitive, efficient, and better-typed code.

---

Black Tortoise (玄武) is one of the Four Symbols in Chinese tradition, symbolizing the north, winter, and the water element. Its image is a combination of a tortoise and a snake, representing:

• Stability & Longevity: This project aims to build an enterprise system that stands the test of time—stable and robust.
• Ultimate Defense: Strict DDD boundaries, Dependency Cruiser, and architecture guards protect core business logic from external technology changes.
• Purity & Inclusiveness: The tortoise's solidity and the snake's agility together drive the "purely reactive" power system.

---

Requirements

• Node.js 22+
• pnpm 9+

Installation & Startup

```bash

# Install dependencies

pnpm install

# Start development server

pnpm run start

# Run architecture gate (CI sync)

pnpm run architecture:gate

```

---

We use [Playwright](playwright.config.ts) for UI testing and [dependency-cruiser](scripts/dependency-cruiser.cjs) for static architecture validation.

---

See each module's AGENTS.md and README.md for details.

---

Thank you for contributing to Black-Tortoise! Feel free to open an issue or fork and submit a PR.

• Before submitting, please run:

```bash

pnpm install

pnpm run lint

pnpm run build -- --noEmit

```

• PR Guide: Please include a description of changes, design rationale, related ticket/issue numbers, and necessary tests or validation steps in your PR description.

• Contact: Leave a comment in the project issue or contact the maintainer via email (see repo settings).

---

Tip: If your change affects the architecture gate (e.g., adds cross-layer dependencies), please note it in the PR and attach an ADR or design document.