# Naming Conventions - SmartStack

> **Loaded by:** business-analyse steps when generating codes and routes
> **Purpose:** Define transformation rules between code identifiers (PascalCase) and URL routes (kebab-case)

---

## Module & Application Codes

### In feature.json

- `modules[].code` = **PascalCase** (e.g., `"HumanResources"`, `"TimeManagement"`)
- `metadata.application` = **PascalCase** (e.g., `"HumanResources"`)
- Used for: C# namespaces, file paths, class names, folder structure

### In URL Routes

- **kebab-case lowercase** (e.g., `"/business/human-resources/employees"`)
- Transform: `PascalCase` → `kebab-case` via helper function
- Used for: Web URLs, navigation routes, API paths

---

## Transformation Rules

| Source | Format | Example | Usage |
|--------|--------|---------|-------|
| Module code | `PascalCase` | `HumanResources` | C# files, classes, namespaces |
| Application code | `PascalCase` | `HumanResources` | Namespaces, folders |
| Context code | `lowercase` | `business` | URLs, routes, contexts |
| Route path | `kebab-case` | `/business/human-resources` | Web URLs, navigation |
| Section code | `kebab-case` | `time-tracking`, `approve` | URLs, API paths, sections |
| Resource code | `kebab-case` | `repair-grid`, `employee-form` | Component IDs, resources |

---

## Why These Conventions?

### PascalCase for Code
- **C# Standard**: Namespaces, classes, properties follow PascalCase
- **File Structure**: Matches .NET project conventions
- **Compile-time**: Enforced by compiler and naming analyzers

### kebab-case for URLs
- **Web Standard**: Readable, SEO-friendly, case-insensitive
- **REST API Convention**: Lowercase routes with hyphens
- **Frontend Compatibility**: React Router, Vue Router expect lowercase
- **Database Storage**: Navigation routes stored lowercase prevent case mismatch errors

### Separation of Concerns
- **Code Identity** ≠ **URL Identity**
- Backend uses PascalCase internally
- URLs transform to kebab-case at persistence layer (seed data)
- Frontend consumes kebab-case routes from database

---

## Helper Functions

### C# (Backend Seed Data)

**Location:** `NavigationSeedData.cs` templates in core-seed-data.md

**Usage:**
```csharp
Route = ToKebabCase($"/{contextCode}/{appCode}/{moduleCode}")
```

**Transformation Examples:**
- `HumanResources` → `human-resources`
- `TimeManagement` → `time-management`
- `Projects` → `projects` (single word, no change)
- `AI` → `ai` (acronym lowercase)

**Implementation:** See `templates/skills/ralph-loop/references/core-seed-data.md` line 162

### JavaScript (BA Handoff Generation)

**Location:** Used in step-05a-handoff.md when building seedDataCore

**Usage:**
```javascript
const route = `/${contextCode}/${toKebabCase(appCode)}/${toKebabCase(moduleCode)}`;
```

**Implementation:**
```javascript
function toKebabCase(code) {
  return code
    .replace(/([a-z])([A-Z])/g, '$1-$2')
    .toLowerCase();
}
```

### TypeScript (Frontend MCP)

**Location:** Used in scaffold_routes and validate_frontend_routes

**Usage:**
```typescript
const webPath = `/${navRoute.split('.').map(toKebabCase).join('/')}`;
```

**Implementation:**
```typescript
function toKebabCase(str: string): string {
  return str
    .replace(/([a-z])([A-Z])/g, '$1-$2')
    .toLowerCase();
}
```

---

## Validation

### During Generation (ralph-loop)

POST-CHECK after NavigationSeedData generation:

```bash
# Detect routes with uppercase
grep -E 'Route = "?/[^"]*[A-Z]' Infrastructure/Persistence/Seeding/Data/*/NavigationSeedData.cs
```

If match found → ERROR, routes not transformed to kebab-case.

### Via MCP

```bash
validate_frontend_routes
```

**Detects:**
- Routes with uppercase in URLs
- Seed data routes not matching frontend expectations
- PascalCase URLs without kebab-case conversion

**Output Example:**
```
❌ Case mismatch detected (1 routes with uppercase):
   Route "business.humanresources" uses PascalCase in URL.
   Found: business/HumanResources → Expected: business/human-resources
   Fix: Use ToKebabCase() in NavigationSeedData route generation
```

---

## Common Pitfalls

### ❌ Generating Routes Without Transformation

**Wrong (causes 404 on menu click):**
```csharp
Route = $"/{contextCode}/{appCode}/{moduleCode}"
// Result: /business/HumanResources/Projects
```

**Correct:**
```csharp
Route = ToKebabCase($"/{contextCode}/{appCode}/{moduleCode}")
// Result: /business/human-resources/projects
```

### ❌ Hardcoding Routes in lowercase

**Wrong (loses traceability to code):**
```csharp
Route = "/business/humanresources"  // Flattens multi-word into single word
```

**Correct:**
```csharp
Route = ToKebabCase($"/{contextCode}/{appCode}")
// If appCode = "HumanResources" → /business/human-resources
```

### ❌ Inconsistent Section/Resource Codes

**Wrong (mixing conventions):**
```json
{
  "code": "TimeTracking",  // PascalCase
  "route": "/time-tracking"  // kebab-case route doesn't match
}
```

**Correct:**
```json
{
  "code": "time-tracking",  // kebab-case from start
  "route": "/business/human-resources/time-tracking"
}
```

Sections and resources ALWAYS use kebab-case (no transformation needed).

---

## Examples

### Full Hierarchy Example

**BA Input (feature.json):**
```json
{
  "metadata": {
    "context": "business",
    "application": "HumanResources"
  },
  "modules": [
    { "code": "TimeManagement" },
    { "code": "Projects" }
  ]
}
```

**Generated Routes (seed data):**
```
Application: /business/human-resources
Module 1:    /business/human-resources/time-management
Module 2:    /business/human-resources/projects
```

**C# Code Structure:**
```
src/Domain/Entities/Business/HumanResources/TimeManagement/TimeEntry.cs
src/Application/Services/Business/HumanResources/TimeManagement/TimeEntryService.cs
src/API/Controllers/Business/HumanResources/TimeManagementController.cs
```

**Frontend Routes (React Router):**
```tsx
<Route path="/business/human-resources/time-management" element={<TimeManagementPage />} />
<Route path="/business/human-resources/projects" element={<ProjectsPage />} />
```

---

## References

- **Template:** `templates/skills/ralph-loop/references/core-seed-data.md`
- **Validation:** `src/mcp/tools/validate-frontend-routes.ts`
- **POST-CHECK:** `templates/skills/ralph-loop/steps/step-02-execute.md` (section 5)
- **Handoff:** `templates/skills/business-analyse/steps/step-05a-handoff.md` (section 4.6)
