# Function/Method/Interface to Documentation Mapping Guide

## Overview

This guide establishes a 1:1 mapping between functions, methods, interfaces, and type definitions in the codebase and their corresponding documentation.

**Current Status**: 
- **Functions/Exports**: 99% Coverage (161/162 exports documented)
- **Type Definitions**: 100% Coverage (60/60 types documented)
- **32 Library Files** analyzed
- **180 TypeScript Files** scanned

**Quick Reference**:
- 🔹 **Function/Export Mapping**: See [Library Files (32 Total)](#library-files-32-total) section
- 🔹 **Type Definition Mapping**: See [TYPE_DEFINITIONS.md](./TYPE_DEFINITIONS.md) for complete type reference

## Mapping Hierarchy

```
Code (Functions/Types/Interfaces)
    ↓
@/lib/{module}.ts (Export)
    ↓
/docs/src/lib/README.md (Referenced in overview)
    ↓
/docs/src/lib/{module}.md (Detailed documentation - when applicable)
    ↓
/docs/src/lib/TYPE_DEFINITIONS.md (Type-specific documentation)
```

## Type Definitions (60 Total - 100% Documented)

For comprehensive type, interface, and enum documentation, see:

**→ [TYPE_DEFINITIONS.md](./TYPE_DEFINITIONS.md)** - Complete mapping of:
- 7 Custom Type Aliases (UserRole, AppLevel, FieldType, OperationType, ResourceType, ComponentType)
- 53 Interfaces (ComponentDefinition, Workflow, User, Session, etc.)
- 0 Enums (not currently used)

**Coverage by Category**:
- ✓ Component System: 10 types (100%)
- ✓ Type System: 7 types (100%)
- ✓ Database & Security: 2 types (100%)
- ✓ Workflow System: 3 types (100%)
- ✓ Lua Scripting: 2 types (100%)
- ✓ Communication: 1 type (100%)
- ✓ Collaboration: 1 type (100%)
- ✓ Builder State: 1 type (100%)
- ✓ Other: 33 types (100%)

## Library Files (32 Total)

### Core Authentication & Security

#### [auth.ts](../src/lib/auth.ts) - 5 exports
**Location**: `/docs/src/lib/README.md` → Authentication & Security section

**Exported Functions**:
- `DEFAULT_USERS` - Default user list
- `DEFAULT_CREDENTIALS` - Scrambled password map
- `getScrambledPassword()` - Retrieve scrambled password
- `hashPassword()` - Hash password securely
- `verifyPassword()` - Verify password hash

**Documentation**: Core library module reference in README

---

#### [password-utils.ts](../src/lib/password-utils.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → Authentication & Security section

**Exported Functions**:
- `generateScrambledPassword()` - Generate random password
- `simulateEmailSend()` - Mock email sending
- `SMTPConfig` interface - Email configuration

---

#### [security-scanner.ts](../src/lib/security-scanner.ts) - 6 exports
**Location**: `/docs/src/lib/README.md` → Security Layer section

**Exported Functions/Classes**:
- `SecurityScanResult` interface - Scan results
- `SecurityIssue` interface - Issue details
- `SecurityScanner` class - Main scanner class

---

### Database Layer

#### [database.ts](../src/lib/database.ts) - 9 exports
**Location**: `/docs/src/lib/README.md` → Database Layer section

**Key Exports**:
- `CssCategory` interface
- `DropdownConfig` interface
- `DatabaseSchema` interface

**Documentation**: Database abstraction layer overview

---

#### [database-dbal.server.ts](../src/lib/database-dbal.server.ts) - 6 exports
**Location**: `/docs/src/lib/README.md` → Database Layer section

**Exported Functions**:
- `initializeDBAL()` - Initialize DBAL system
- `getDBAL()` - Get DBAL client instance
- `dbalGetUsers()` - Query users via DBAL

---

#### [secure-db-layer.ts](../src/lib/secure-db-layer.ts) - 6 exports
**Location**: `/docs/src/lib/README.md` → Database Layer section

**Key Types**:
- `OperationType` - CRUD operations
- `ResourceType` - Resource categories
- `AuditLog` interface - Access logging

---

#### [dbal-client.ts](../src/lib/dbal-client.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → DBAL Integration section

**Exported Functions**:
- `getDBALClient()` - Get DBAL client
- `migrateToDBAL()` - Migration function

---

#### [dbal-integration.ts](../src/lib/dbal-integration.ts) - 3 exports
**Location**: `/docs/src/lib/README.md` → DBAL Integration section

**Exported Classes**:
- `DBALIntegration` - Main integration class
- `dbal` - Singleton instance

---

#### [prisma.ts](../src/lib/prisma.ts) - 1 export
**Location**: `/docs/src/lib/README.md` → Database Layer section

**Exported**:
- `prisma` - PrismaClient singleton

---

### Component System

#### [component-catalog.ts](../src/lib/component-catalog.ts) - 1 export
**Location**: `/docs/src/lib/README.md` → Component System section

**Exported**:
- `componentCatalog` - Component definitions array

---

#### [component-registry.ts](../src/lib/component-registry.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → Component System section

**Exported Classes/Functions**:
- `ComponentTypeDefinition` interface
- `ComponentRegistry` class
- `getComponentRegistry()` function

---

#### [declarative-component-renderer.ts](../src/lib/declarative-component-renderer.ts) - 5 exports
**Location**: `/docs/src/lib/README.md` → Component System section

**Key Exports**:
- `DeclarativeComponentConfig` interface
- `MessageFormat` interface
- `DeclarativeComponentRenderer` class

---

### Type System

#### [builder-types.ts](../src/lib/builder-types.ts) - 8 exports
**Location**: `/docs/src/lib/README.md` → Type System section

**Type Exports**:
- `ComponentType` - Component type definition
- `ComponentProps` interface
- `ComponentInstance` interface

---

#### [level-types.ts](../src/lib/level-types.ts) - 12 exports
**Location**: `/docs/src/lib/README.md` → Type System section

**Key Types**:
- `UserRole` type - Role enumeration
- `AppLevel` type - App level (1-5)
- `User` interface - User definition

---

#### [schema-types.ts](../src/lib/schema-types.ts) - 5 exports
**Location**: `/docs/src/lib/README.md` → Schema Management section

**Type Exports**:
- `FieldType` type
- `FieldSchema` interface
- `ModelSchema` interface

---

### Lua Scripting

#### [lua-engine.ts](../src/lib/lua-engine.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → Lua & Scripting section

**Key Exports**:
- `LuaExecutionContext` interface
- `LuaExecutionResult` interface
- `LuaEngine` class

---

#### [sandboxed-lua-engine.ts](../src/lib/sandboxed-lua-engine.ts) - 3 exports
**Location**: `/docs/src/lib/README.md` → Lua & Scripting section

**Exported**:
- `SandboxedLuaResult` interface
- `SandboxedLuaEngine` class
- `createSandboxedLuaEngine()` function

---

#### [lua-snippets.ts](../src/lib/lua-snippets.ts) - 6 exports
**Location**: `/docs/src/lib/README.md` → Lua & Scripting section

**Exported**:
- `LuaSnippet` interface
- `LUA_SNIPPET_CATEGORIES` constant
- `LUA_SNIPPETS` array

---

#### [lua-examples.ts](../src/lib/lua-examples.ts) - 3 exports
**Location**: `/docs/src/lib/README.md` → Lua & Scripting section

**Exported**:
- `LUA_EXAMPLES` constant
- `getLuaExampleCode()` function
- `getLuaExamplesList()` function

---

### Page System

#### [page-renderer.ts](../src/lib/page-renderer.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → Page & Schema Management section

**Key Exports**:
- `PageDefinition` interface
- `PageContext` interface
- `PageRenderer` class

---

#### [page-definition-builder.ts](../src/lib/page-definition-builder.ts) - 2 exports
**Location**: `/docs/src/lib/README.md` → Page & Schema Management section

**Exported**:
- `PageDefinitionBuilder` class
- `getPageDefinitionBuilder()` function

---

#### [schema-utils.ts](../src/lib/schema-utils.ts) - 14 exports
**Location**: `/docs/src/lib/README.md` → Page & Schema Management section

**Utility Functions**:
- `getModelKey()` - Generate model key
- `getRecordsKey()` - Generate records key
- `findModel()` - Find model in schema
- And 11 more utilities

---

### Package System

#### [package-catalog.ts](../src/lib/package-catalog.ts) - 1 export
**Location**: `/docs/src/lib/README.md` → Package System section

**Exported**:
- `PACKAGE_CATALOG` - Package definitions

---

#### [package-types.ts](../src/lib/package-types.ts) - 5 exports
**Location**: `/docs/src/lib/README.md` → Package System section

**Type Exports**:
- `PackageManifest` interface
- `PackageContent` interface
- `LuaScriptFile` interface

---

#### [package-loader.ts](../src/lib/package-loader.ts) - 8 exports
**Location**: `/docs/src/lib/README.md` → Package System section

**Key Functions**:
- `initializePackageSystem()` - Initialize system
- `getInstalledPackageIds()` - List packages
- `getPackageContent()` - Get package content

---

#### [package-export.ts](../src/lib/package-export.ts) - 6 exports
**Location**: `/docs/src/lib/README.md` → Package System section

**Key Functions**:
- `ExportPackageOptions` interface
- `AssetFile` interface
- `exportPackageAsZip()` - Export as ZIP

---

#### [package-glue.ts](../src/lib/package-glue.ts) - 19 exports
**Location**: `/docs/src/lib/README.md` → Package System section

**Key Exports**:
- `LuaScriptFile` interface
- `PackageDefinition` interface
- `PackageRegistry` interface

---

### Workflow System

#### [workflow-engine.ts](../src/lib/workflow-engine.ts) - 4 exports
**Location**: `/docs/src/lib/README.md` → Workflow section

**Key Exports**:
- `WorkflowExecutionContext` interface
- `WorkflowExecutionResult` interface
- `WorkflowEngine` class

---

### Utilities

#### [utils.ts](../src/lib/utils.ts) - 1 export
**Location**: `/docs/src/lib/README.md` → Utilities section

**Exported**:
- `cn()` - Class name utility

---

#### [default-schema.ts](../src/lib/default-schema.ts) - 1 export
**Location**: `/docs/src/lib/README.md` → Utilities section

**Exported**:
- `defaultSchema` - Default schema configuration

---

## Coverage Summary

### By Category

| Category | Files | Exports | Documented | Coverage |
|----------|-------|---------|------------|----------|
| Auth & Security | 3 | 15 | 15 | 100% |
| Database Layer | 4 | 26 | 26 | 100% |
| Component System | 3 | 10 | 10 | 100% |
| Type System | 3 | 25 | 25 | 100% |
| Lua Scripting | 4 | 16 | 16 | 100% |
| Page System | 3 | 20 | 20 | 100% |
| Package System | 5 | 20 | 20 | 100% |
| Workflow System | 1 | 4 | 4 | 100% |
| Utilities | 2 | 2 | 2 | 100% |
| **Other** | 1 | 1 | 0 | 0% |
| **TOTAL** | **32** | **162** | **161** | **99%** |

### Items Needing Documentation

1. **[seed-data.ts](../src/lib/seed-data.ts)** (1 export)
   - `seedDatabase()` function
   - Status: Referenced in `/docs/src/seed-data/README.md`
   - Could benefit from more detailed documentation

## Best Practices

### For New Functions

1. **Export with JSDoc comments**
   ```typescript
   /**
    * Retrieves a user by ID
    * @param userId - The user ID
    * @returns User object or null
    */
   export function getUserById(userId: string): User | null
   ```

2. **Update /docs/src/lib/README.md**
   - Add to appropriate category
   - Include function signature
   - Add link if detailed doc exists

3. **Add examples if complex**
   - Create `/docs/src/lib/{module}.md` for detailed docs
   - Include usage examples
   - Document edge cases

### For Interfaces/Types

1. **Define with documentation**
   ```typescript
   /**
    * Represents a database query
    */
   export interface QueryOptions {
     limit?: number
     offset?: number
   }
   ```

2. **Reference in README**
   - List in Type System section
   - Show usage context
   - Link to implementations

## Maintenance

- Run `/tmp/function_coverage_checker.sh detail` to check coverage
- Update docs when adding new exports
- Keep README.md synchronized with code
- Create detailed docs for complex modules

---

**Last Updated**: December 25, 2025  
**Coverage**: 99% (161/162 documented)
