Architecture Decision: src/core and src/domain separation

[deepracticexs]

Architecture Decision: src/core and src/domain Separation

Context

NodeSpec needs a clear organization for its business logic in the src/ directory. We need to decide between:

• Pure DDD (Domain-Driven Design) approach
• Pure technical layering approach
• Hybrid approach

Decision

We will use a hybrid architecture with both core/ and domain/ subdirectories under src/:

src/
├── package.json           # @deepracticex/nodespec-core
├── index.ts               # Unified exports
├── core/                  # Technical layer
│   ├── template/          # Template generation engine
│   ├── guide/             # Documentation service
│   └── executor/          # Task execution
└── domain/                # Domain layer (for future DDD modules)

Rationale

Why Not Pure DDD?

NodeSpec is primarily a technical product (CLI tool, template engine, task orchestrator), not a business-heavy system:

• No complex business rules that change frequently
• No need for domain experts (product managers)
• Focus on "how to implement" (algorithms) rather than "what to do" (business rules)

DDD is better suited for:

• Business rule-intensive systems (e-commerce, CRM, finance)
• Frequent business logic changes
• Systems requiring domain expert collaboration

Why Not Pure Technical Layering?

While NodeSpec is currently technical, we want flexibility for future expansion:

• May add user management (authentication, authorization)
• May add licensing/subscription logic
• May add complex workflow orchestration

Why Hybrid?

The hybrid approach provides:

1. Clear Separation of Concerns

   • core/: Algorithms, engines, technical services (stable)
   • domain/: Business rules, policies (when needed)

2. Flexibility

   • Start with core/ only
   • Add domain/ modules as business complexity grows

3. Unified API

   // Users don't need to know internal structure
   import { ProjectGenerator } from '@deepracticex/nodespec-core';

4. Open-Closed Principle

   • Open for extension (can add domain modules)
   • Closed for modification (doesn't affect existing code)

Implementation

Package Structure

src/package.json:

{
  "name": "@deepracticex/nodespec-core",
  "exports": {
    ".": "./index.ts",
    "./core/template": "./core/template/index.ts",
    "./core/guide": "./core/guide/index.ts",
    "./core/executor": "./core/executor/index.ts"
  }
}

src/index.ts:

// Export from core modules
export * from './core/template/index.js';
export * from './core/guide/index.js';
export * from './core/executor/index.js';

// Export from domain modules (when needed)
// export * from './domain/user/index.js';

Usage in Apps

// apps/cli/package.json
{
  "dependencies": {
    "@deepracticex/nodespec-core": "workspace:*"
  }
}

// apps/cli/src/commands/project/init.ts
import { ProjectGenerator } from '@deepracticex/nodespec-core';

Examples

Current: Technical Module (core/)

// src/core/template/TemplateEngine.ts
export class TemplateEngine {
  render(template: string, data: object): string {
    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => data[key]);
  }
}

// src/core/template/ProjectGenerator.ts
export class ProjectGenerator {
  async generate(targetDir: string, name: string): Promise<void> {
    await this.copyTemplate(targetDir);
    await this.replaceVariables(targetDir, { name });
    await this.initGit(targetDir);
  }
}

Future: Domain Module (domain/)

If we add user management with complex business rules:

// src/domain/user/User.ts
export class User extends AggregateRoot {
  canAccessFeature(feature: Feature): boolean {
    // Complex business rules
    if (this.subscription.isExpired()) return false;
    if (!this.subscription.plan.includes(feature)) return false;
    return true;
  }
}

Decision Criteria

Use core/ when:

• ✅ Technical implementation (algorithms, data processing)
• ✅ Logic is relatively stable
• ✅ Developers make technical decisions

Use domain/ when:

• ✅ Business rules from product/business team
• ✅ Rules change frequently
• ✅ Need to model real-world concepts (entities, value objects)

Related Issues

• Architecture Decision: Use src/ (core) instead of domains/ for NodeSpec #3 - Architecture Decision: domain vs core
• Build NodeSpec CLI with real-world project: DeepracticeAccount #1 - Build NodeSpec CLI with DeepracticeAccount

Status

✅ Decided and being implemented

[deepracticexs]

Update: Split into Two Packages

After further discussion, we've decided to split src/ into two separate packages instead of one unified package with subdirectories.

New Structure

src/
├── core/
│   ├── package.json          # @deepracticex/nodespec-core
│   ├── index.ts
│   ├── template/
│   │   ├── templates/
│   │   ├── TemplateEngine.ts
│   │   └── ProjectGenerator.ts
│   ├── guide/
│   └── executor/
└── domain/
    ├── package.json          # @deepracticex/nodespec-domain
    ├── index.ts
    └── (future DDD modules)

Package Definitions

@deepracticex/nodespec-core:

{
  "name": "@deepracticex/nodespec-core",
  "private": true,
  "exports": {
    ".": "./index.ts",
    "./template": "./template/index.ts",
    "./guide": "./guide/index.ts",
    "./executor": "./executor/index.ts"
  }
}

@deepracticex/nodespec-domain:

{
  "name": "@deepracticex/nodespec-domain",
  "private": true,
  "exports": {
    ".": "./index.ts"
  }
}

Usage

// apps/cli/package.json
{
  "dependencies": {
    "@deepracticex/nodespec-core": "workspace:*"
  }
}

// apps/cli/src/commands/project/init.ts
import { ProjectGenerator } from '@deepracticex/nodespec-core/template';
import { GuideService } from '@deepracticex/nodespec-core/guide';

// Future: when domain modules are added
// import { UserService } from '@deepracticex/nodespec-domain';

Advantages

1. Clearer Semantics

   • Package name = Responsibility
   • nodespec-core = Technical implementations
   • nodespec-domain = Business logic

2. Independent Evolution

   • Can have independent versions
   • Can publish separately in the future
   • Core (stable) vs Domain (may change frequently)

3. On-Demand Dependencies

   // CLI only needs core
   dependencies: { "@deepracticex/nodespec-core": "workspace:*" }
   
   // Desktop may need both
   dependencies: {
     "@deepracticex/nodespec-core": "workspace:*",
     "@deepracticex/nodespec-domain": "workspace:*"
   }

4. Follows Best Practices

   • Aligns with Nx, Turborepo recommendations
   • Clear module boundaries
   • Better for monorepo tooling

5. Layered Architecture Support

   apps/       → depends on → core + domain
   domain/     → can depend on → core (as infrastructure)
   core/       → independent
   

Workspace Configuration

# pnpm-workspace.yaml
packages:
  - "src/core"
  - "src/domain"
  - "packages/*"
  - "apps/*"
  - "services/*"

This approach provides better separation of concerns and makes the architecture more explicit.

[deepracticexs]

Migrated to Architecture Decision Record in #6