# Code Element Identification Methodology

This guide provides comprehensive methodology for identifying code elements at the C4 (Code) level of the C4 Model.

---

## Code Element Types

### 1. Classes

**Detection patterns:**
```typescript
// TypeScript/JavaScript
class ClassName { }
export class ClassName { }
abstract class ClassName { }
export default class ClassName { }
```

```python
# Python
class ClassName:
    pass

class ClassName(ParentClass):
    pass

class ClassName(ABC):  # Abstract
    pass
```

```java
// Java
public class ClassName { }
public abstract class ClassName { }
public final class ClassName { }
```

**ID format:** `{component}-{class-name}-class`
**Example:** `auth-service-user-manager-class`

---

### 2. Functions

**Detection patterns:**
```typescript
// TypeScript/JavaScript
function functionName() { }
export function functionName() { }
const functionName = () => { }
export const functionName = () => { }
export default function functionName() { }
```

```python
# Python
def function_name():
    pass
```

```java
// Java - methods are always in classes
public static void functionName() { }
```

**ID format:** `{component}-{function-name}`
**Example:** `auth-service-validate-token`

---

### 3. Async Functions

**Detection patterns:**
```typescript
// TypeScript/JavaScript
async function functionName() { }
export async function functionName() { }
const functionName = async () => { }
```

```python
# Python
async def function_name():
    pass
```

**ID format:** `{component}-{function-name}`
**Example:** `auth-service-authenticate`

---

### 4. Methods

**Detection patterns:**
```typescript
// TypeScript/JavaScript - inside class
class Example {
  methodName() { }
  async methodName() { }
  private methodName() { }
  static methodName() { }
  get propertyName() { }
  set propertyName(value) { }
}
```

```python
# Python
class Example:
    def method_name(self):
        pass

    @classmethod
    def class_method(cls):
        pass

    @staticmethod
    def static_method():
        pass
```

**ID format:** `{class-id}-{method-name}`
**Example:** `auth-service-class-get-user`

---

### 5. Interfaces

**Detection patterns:**
```typescript
// TypeScript
interface InterfaceName { }
export interface InterfaceName { }
interface InterfaceName extends OtherInterface { }
```

```java
// Java
public interface InterfaceName { }
public interface InterfaceName extends OtherInterface { }
```

**ID format:** `{component}-{interface-name}-interface`
**Example:** `auth-service-i-user-repository-interface`

---

### 6. Types

**Detection patterns:**
```typescript
// TypeScript
type TypeName = string | number;
export type TypeName = { field: string };
type TypeName<T> = T[];
type TypeName = Pick<OtherType, 'field'>;
```

**ID format:** `{component}-{type-name}-type`
**Example:** `auth-service-user-credentials-type`

---

### 7. Constants

**Detection patterns:**
```typescript
// TypeScript/JavaScript
const CONSTANT_NAME = 'value';
export const CONSTANT_NAME = 42;
export const CONFIG = { ... } as const;
```

```python
# Python
CONSTANT_NAME = 'value'
MAX_RETRIES = 3
```

```java
// Java
public static final String CONSTANT_NAME = "value";
public static final int MAX_RETRIES = 3;
```

**ID format:** `{component}-{constant-name}-const`
**Example:** `auth-service-max-login-attempts-const`

---

### 8. Enums

**Detection patterns:**
```typescript
// TypeScript
enum EnumName { A, B, C }
export enum EnumName { A = 'a', B = 'b' }
const enum EnumName { A, B, C }
```

```python
# Python
from enum import Enum

class EnumName(Enum):
    A = 1
    B = 2
```

```java
// Java
public enum EnumName { A, B, C }
```

**ID format:** `{component}-{enum-name}-enum`
**Example:** `auth-service-user-role-enum`

---

### 9. Decorators

**Detection patterns:**
```typescript
// TypeScript
function DecoratorName(target: any) { }
export function DecoratorName(): MethodDecorator { }
```

```python
# Python
def decorator_name(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper
```

**ID format:** `{component}-{decorator-name}-decorator`
**Example:** `auth-service-authenticated-decorator`

---

## Significance Criteria

Only document a code element if **ANY** of these apply:

### Public API
- Exported from module
- Part of public interface
- Used by external callers

### Complexity
- Lines of code > 20
- Cyclomatic complexity > 4
- Cognitive complexity > 10

### Architecture
- Implements design pattern
- Key abstraction or facade
- Entry point or controller action

### Business Logic
- Contains critical business rules
- Handles sensitive data
- Has security implications

### Dependencies
- Multiple callers (> 2)
- Multiple dependencies (> 3)
- Central to component

---

## Detection Commands

```bash
# TypeScript - Find classes
grep -rn "^export class\|^class " src/ --include="*.ts"

# TypeScript - Find functions
grep -rn "^export function\|^export async function\|^export const.*=.*=>" src/ --include="*.ts"

# TypeScript - Find interfaces
grep -rn "^export interface\|^interface " src/ --include="*.ts"

# TypeScript - Find types
grep -rn "^export type\|^type " src/ --include="*.ts"

# TypeScript - Find enums
grep -rn "^export enum\|^enum " src/ --include="*.ts"

# Python - Find classes
grep -rn "^class " src/ --include="*.py"

# Python - Find functions
grep -rn "^def \|^async def " src/ --include="*.py"

# Count lines per file
wc -l src/**/*.ts | sort -n
```

---

## Naming Conventions

### ID Format
- Use kebab-case
- Include component prefix
- Include element type suffix where helpful
- Pattern: `{component-id}-{element-name}[-{type}]`

### Name Field
- Preserve original case (PascalCase, camelCase, snake_case)
- Use exact name from source code

### Examples

| Source Name | ID | name |
|------------|-----|------|
| `UserService` | `auth-user-service-class` | `UserService` |
| `authenticate` | `auth-authenticate` | `authenticate` |
| `IUserRepository` | `auth-i-user-repository-interface` | `IUserRepository` |
| `LoginCredentials` | `auth-login-credentials-type` | `LoginCredentials` |
| `MAX_RETRIES` | `auth-max-retries-const` | `MAX_RETRIES` |
| `UserRole` | `auth-user-role-enum` | `UserRole` |

---

## Best Practices

### ✅ DO:
- Focus on significant, public elements
- Use consistent ID naming
- Preserve original casing in name field
- Document all public API elements
- Include classes that define key abstractions

### ❌ DON'T:
- Document every private helper function
- Document trivial getters/setters
- Document test files as code elements
- Use file names as element IDs
- Skip exported functions/classes