Update mapping domain to use new terminology

[Diplow]

Issue: Update mapping domain to use new terminology

Date: 2025-06-20
Status: Open
Tags: #refactor #architecture #tech #mapping #medium
Branch: mapping-terminology-update

Problem Statement

The mapping domain uses outdated terminology that doesn't align with the current conceptual model of the application. This inconsistency makes the codebase harder to understand and maintain.

User Impact

• Developers are confused by mismatched terminology between UI and domain code
• New contributors need extra time to understand the mapping between old and new terms
• Code maintainability is reduced due to conceptual misalignment

Steps to Reproduce

1. Navigate to /src/lib/domains/mapping/
2. Review the domain models and terminology used
3. Compare with the UI terminology in /src/app/map/
4. Notice the mismatch between domain terms and UI terms

Environment

• Codebase-wide issue
• Affects all developers working on mapping features
• Frequency: Constant friction during development

Related Issues

• Previous refactoring efforts may have updated UI but not domain layer
• Documentation may need updates after terminology change

Terminology Mapping Required

Old terms → New terms:

• item/mapItem → tile
• expanded view → frame
• canvas/board → map
• reorder → swap
• relocate → move
• version → generation
• descendants → children
• focus/center → centerTile

Additional Context

This is a technical debt issue that affects code clarity and developer experience. The domain layer should use the same conceptual model as the UI to maintain consistency throughout the application.

[Diplow]

This is not so much a missmatch between the "front" code and the domain code than it is a lack of clarity compared to what is conceptualised. Of course we will try to align language all over the code base to the domain, but the domain is the most important place to define the correct language since core functionnalities will be defined here. This comes from domain driven design principles and while there is only one developer currently working on the project, AI code most of the work here and consistent language has a proven track records of better results when it comes to both humans and AI.

Once this refactor has happened we can hope for an up to date README.md in the mapping domain, that will greatly improve all human and AI understanding of the codebase.

[Diplow]

Updated Issue Documentation

After incorporating feedback, here's the updated issue documentation:

Issue: Update mapping domain to use new terminology

Date: 2025-06-20
Status: Open
Tags: #refactor #architecture #tech #mapping #medium
GitHub Issue: #49
Branch: mapping-terminology-update

Problem Statement

The mapping domain uses outdated terminology that doesn't align with the current conceptual model of the application. This is not just a mismatch between front-end code and domain code, but rather a lack of clarity compared to what is conceptualized. Consistent language has proven track records of better results when it comes to both humans and AI.

User Impact

• Developers are confused by mismatched terminology between UI and domain code
• New contributors need extra time to understand the mapping between old and new terms
• Code maintainability is reduced due to conceptual misalignment
• AI assistants have difficulty understanding and working with inconsistent terminology
• Domain-driven design principles are violated by unclear language

Steps to Reproduce

1. Navigate to /src/lib/domains/mapping/
2. Review the domain models and terminology used
3. Compare with the UI terminology in /src/app/map/
4. Notice the mismatch between domain terms and UI terms

Environment

• Codebase-wide issue
• Affects all developers working on mapping features
• Frequency: Constant friction during development

Related Issues

• Previous refactoring efforts may have updated UI but not domain layer
• Documentation may need updates after terminology change

Terminology Mapping Required

Old terms → New terms:

• item/mapItem → tile
• expanded view → frame
• canvas/board → map
• reorder → swap
• relocate → move
• version → generation
• descendants → children
• focus/center → centerTile

Additional Context

This is a technical debt issue that affects code clarity and developer experience. The domain layer should use the same conceptual model as the UI to maintain consistency throughout the application.

[Diplow]

I am an AI assistant acting on behalf of @Diplow

To clarify: The previous comment was posted by me (Claude) while helping to manage this issue. Going forward, I will always identify myself as an AI assistant at the beginning of any GitHub comments to ensure transparency about AI-generated content.

[Diplow]

Context

I am an AI assistant acting on behalf of @Diplow

Architecture Overview

The mapping domain (/src/lib/domains/mapping/) implements the core logic for tile management and hierarchical structures following Domain-Driven Design principles. It's structured with clear separation between domain objects, repositories, services, and infrastructure layers.

Key architectural decisions:

• Recent refactoring eliminated separate "Map" entities - now a "map" is represented by a root USER-type MapItem
• Hierarchical structure uses coordinate system with userId, groupId, and path (array of directions)
• Two types of MapItems: USER (root items) and BASE (all other items with parents)

Current Implementation

• Key Components:

  • MapItem domain object - 2,774 occurrences of "item" terminology
  • BaseItem domain object - reference items containing content
  • MappingService - main coordinating service
  • ItemManagementService - handles item-level operations
  • MapManagementService - handles map-level operations

• Current Patterns:

  • Repository pattern with domain objects in _objects/
  • Service layer for business logic
  • Infrastructure layer for database access
  • Actions layer for complex operations

• Dependencies:

  • Used by tRPC routers in /src/server/routers/
  • Consumed by React components via hooks in /src/app/_hooks/
  • Database tables: vde_map_items, vde_base_items

Affected Areas

• Primary Changes:

  • /src/lib/domains/mapping/ - 2,774 occurrences of "item" terminology
  • /src/lib/domains/mapping/ - 58 occurrences of "descendants"
  • Database schema with tables and columns using "item" naming
  • All type definitions in /src/lib/domains/mapping/types/

• Secondary Impact:

  • tRPC routers that expose the domain operations
  • React hooks that consume the API
  • Cache keys throughout the application
  • Database migrations (14 references to "item" in existing migrations)

• Cross-Domain Effects:

  • IAM domain may reference mapping domain types
  • Any external integrations using the API

Technical Considerations

• Constraints:

  • Database column and table names require migration
  • Breaking changes to API contracts
  • Existing data must be preserved during migration

• Risks:

  • Large-scale refactoring (2,774+ changes needed)
  • Potential for introducing bugs during mass renaming
  • Database migration complexity
  • API versioning may be needed for external consumers

• Performance:

  • No performance impact expected from renaming
  • Migration must be carefully planned to avoid downtime

Documentation Status

• Current Docs:

  • /src/lib/domains/mapping/README.md exists and uses "item" terminology
  • Service-level README documents the architecture
  • Infrastructure README explains database patterns

• Terminology Disconnect:

  • Frontend already uses "tile" (1,077 occurrences)
  • Backend uses "item/mapItem" throughout
  • Creates confusion when developers work across layers

Related Code References

• /src/lib/domains/mapping/_objects/map-item.ts - Core domain object definition
• /src/lib/domains/mapping/types/contracts.ts - API contract definitions
• /src/server/db/schema/map.ts - Database schema definitions
• /src/app/map/Tile/ - UI components using "tile" terminology

[Diplow]

This refactor will only be about domain objects, domain repositories, infrastructure repositories and domain actions as a first step. The domain service will keep its current definition first. The database tables will also stay the same for now.

[Diplow]

Also I think we should discuss what are the specific terms we will update, keep and remove but can wait for the /solution planning phase. As for now, you should get a good understanding of what are the current objects, the current actions, the current repositories and infrastructure repositories and the current service methods (even if we keep the same methods for now)

[Diplow]

Context Update - Scope Restrictions

I am an AI assistant acting on behalf of @Diplow

Based on your comments, I've updated the issue documentation with the following scope restrictions:

Scope Restrictions

Initial refactoring will focus on:

• Domain objects in _objects/
• Repositories in _repositories/
• Actions in _actions/

Will NOT change (in this phase):

• Domain services
• Database tables and schema
• API endpoints

Approach:
During solution planning, we should:

• List all current objects, actions, repositories, and service methods
• Discuss which terms to update, keep, or remove
• Focus on aligning the domain language first before propagating changes outward

This significantly reduces the initial scope from 2,774 changes to just the core domain layer, making it a more manageable refactoring that can be done without breaking changes to the database or API.

[Diplow]

Documentation Update - New Dual-File Approach

I am an AI assistant acting on behalf of @Diplow

I've updated the /issue command to create two files instead of one:

1. Issue File (2025-06-20-mapping-domain-terminology-update.md)

• Purpose: Synthetic, up-to-date view of the issue
• Content: Current state only, no history
• Updates: Each command updates relevant sections

2. Log File (2025-06-20-mapping-domain-terminology-update.log.md)

• Purpose: Complete history and detailed documentation
• Content: All investigations, decisions, and evolution
• Updates: Each command appends timestamped entries

Benefits

• Issue file stays clean and scannable
• Log file preserves all context and reasoning
• Easy to see both current state and how we got there
• Better for long-running issues with multiple iterations

I've created a log file for this issue that documents everything from creation through the context analysis and scope restrictions. Future commands will update both files appropriately.

[Diplow]

I am an AI assistant acting on behalf of @Diplow

Context Analysis Complete

Context

I am an AI assistant acting on behalf of @Diplow

Existing Documentation

• README Files:

  • /src/lib/domains/README.md - Explains general domain structure (entities, actions, services, repositories pattern)
  • /src/lib/domains/mapping/README.md - Main mapping domain overview with outdated references to HexMap aggregate
  • /src/lib/domains/mapping/_actions/README.md - Detailed actions layer documentation with current structure
  • /src/lib/domains/mapping/infrastructure/map-item/README.md - Infrastructure patterns for data access
  • /src/lib/domains/mapping/services/README.md - Services layer architecture and contracts

• Architecture Docs:

  • Domain follows DDD with clear separation: objects → repositories → actions → services → infrastructure
  • Recent refactoring eliminated HexMap aggregate - now uses MapItem directly
  • Hierarchical coordinate system with userId, groupId, and path array

• Documentation vs Reality:

  • ✅ DDD structure and layered architecture match documentation
  • ✅ Actions and services layer organization as documented
  • ❌ Main README references non-existent HexMap entity and hex-map.ts files
  • ❌ Documentation uses "item" terminology while UI uses "tile"
  • 📝 No terminology glossary or mapping guide exists

Domain Overview

The mapping domain (/src/lib/domains/mapping/) implements a hierarchical hexagonal tile system following Domain-Driven Design principles:

• Architecture: Clean DDD with domain objects at core, wrapped by repositories, orchestrated by actions, exposed through services
• Coordinate System: Hierarchical positioning using coord_user_id, coord_group_id, and path (array of directions)
• Item Types: Two distinct types - USER (root maps) and BASE (child tiles with parents)
• Recent Evolution: Simplified from separate Map/MapItem entities to unified MapItem approach

Key Components

• MapItem: Core domain object (1,938 occurrences of "item") representing tiles in hierarchy

  • Properties: id, coordinates, itemType, parentId, refItemId
  • Methods: validation, coordinate management, parent-child relationships

• BaseItem: Reference content for map items

  • Properties: id, title, descr, link
  • Provides the actual data displayed in tiles

• MapItemActions: Business logic orchestration with specialized helpers

  • MapItemCreationHelpers: Handle item creation with coordinate assignment
  • MapItemMovementHelpers: Manage move operations and descendant updates
  • MapItemQueryHelpers: Complex queries for fetching items

• Services Layer: High-level API with specialized services

  • MappingService: Main coordinator
  • MapManagementService: Map-level operations
  • ItemManagementService: Item-level operations
  • ItemCrudService: CRUD operations
  • ItemQueryService: Query operations

Implementation Details

• File Organization:

  _objects/
    ├── base-item.ts
    └── map-item.ts
  _repositories/
    ├── base-item.ts
    └── map-item.ts
  _actions/
    ├── map-item.actions.ts
    └── helpers/
  services/
    ├── mapping.service.ts
    └── specialized services
  

• Naming Conventions:

  • Backend: "item", "mapItem", "descendants", "move", "swap"
  • Frontend: "tile", "children", "centerTile"
  • Database: "map_items", "base_items" tables

• Design Patterns:

  • Repository pattern for data abstraction
  • Service layer for API contracts
  • Actions for complex business logic
  • Helper classes for code organization

• Data Flow:

  1. Services receive requests with contracts
  2. Actions orchestrate business logic
  3. Repositories handle data access
  4. Domain objects maintain invariants

Code Examples

// Current domain object (map-item.ts)
export class MapItem {
  public readonly id: number;
  public readonly coord: Coord;
  public readonly itemType: MapItemType;
  public readonly parentId: number | null;
  
  // Current terminology in methods
  public validate(): void { ... }
  public isCenter(): boolean { ... }
}

// Current service API (mapping.service.ts)
export class MappingService {
  async getMapsForUser(userId: number): Promise<MapContract[]>
  async getMapItems(mapId: number): Promise<MapItemContract[]>
  async moveMapItem(params: MoveMapItemParams): Promise<MoveMapItemResult>
}

// Database schema (map-items.ts)
export const mapItems = createTable("map_items", {
  id: integer("id").primaryKey(),
  coord_user_id: integer("coord_user_id"),
  coord_group_id: integer("coord_group_id"),
  path: varchar("path", { length: 255 }),
  item_type: varchar("item_type", { length: 50 }),
  parent_id: integer("parent_id"),
  ref_item_id: integer("ref_item_id")
});

Dependencies and Integration

• Internal Dependencies:

  • Uses hex-coordinates package for spatial calculations
  • Depends on IAM domain for user context
  • Integrates with database through Drizzle ORM

• External Consumers:

  • tRPC routers in /src/server/routers/map.ts
  • React hooks in /src/app/_hooks/
  • UI components in /src/app/map/

• API Contracts:

  • MapContract, MapItemContract for external communication
  • DTOs maintain backward compatibility

• Database Schema:

  • vde_map_items: Main table with coordinates and hierarchy
  • vde_base_items: Content storage
  • vde_user_mapping: Auth user to mapping user bridge