Core Library Organization

Introduction

The core/lib/ directory is the heart of the application's business logic, utilities, and services. It contains over 15 major modules that provide everything from API handling to authentication, from entity management to i18n support. Understanding this structure is crucial for effective development.

Directory Structure Overview

core/lib/
├── api/                    # API utilities and CRUD generation
├── auth/                   # Authentication configuration
├── config/                 # System configuration
├── docs/                   # Documentation utilities
├── email/                  # Email service abstraction
├── entities/               # Entity system core
├── i18n/                   # Internationalization utilities
├── oauth/                  # OAuth provider integrations
├── plugins/                # Plugin system utilities
├── registries/             # AUTO-GENERATED registries ⚠️
├── security/               # Security utilities
├── services/               # Business logic services
├── theme/                  # Theme utilities
└── utils/                  # General utilities

---

Critical Modules

1. Registries Module (registries/) ⚠️

⚠️ CRITICAL WARNING: ALL FILES ARE AUTO-GENERATED. NEVER EDIT MANUALLY.

Purpose: Build-time generated static registries for instant runtime access.

Key Files:

registries/
├── entity-registry.ts              # Server-side entity registry
├── entity-registry.client.ts       # Client-safe entity subset
├── plugin-registry.ts              # Server-side plugin registry
├── plugin-registry.client.ts       # Client-safe plugin subset
├── theme-registry.ts               # Theme configurations
├── translation-registry.ts         # i18n message loaders
├── route-handlers.ts               # API route handlers
├── config-registry.ts              # Entity configs
├── docs-registry.ts                # Documentation index
└── index.ts                        # Unified exports

Generation:

# Generated by scripts/build-registry.mjs
pnpm registry:build        # One-time build
pnpm registry:build-watch  # Watch mode (auto-rebuild on changes)

Usage:

// ✅ CORRECT - Access via registry
import { ENTITY_REGISTRY } from '@/core/lib/registries/entity-registry'
const taskConfig = ENTITY_REGISTRY.tasks

// ❌ WRONG - Direct import from contents
import { taskConfig } from '@/contents/themes/default/entities/tasks/tasks.config'

Performance Impact:

• Build-time registry: ~6ms
• Runtime import: ~140ms
• Improvement: ~17,255x faster

Rules:

1. NEVER edit files in registries/ manually
2. ALWAYS regenerate with pnpm registry:build
3. ALWAYS access content via registries
4. Use server vs client versions appropriately

---

2. API Module (api/)

Purpose: API route generation, CRUD operations, authentication, response formatting.

Key Files:

api/
├── entities.ts              # Entity CRUD wrapper
├── entity-handler.ts        # Dynamic route handler generator
├── helpers.ts               # Response formatting, pagination
├── cache.ts                 # Redis/memory caching
├── keys.ts                  # API key scopes
├── meta.middleware.ts       # Metadata integration
└── auth/                    # Dual authentication
    ├── dual-auth.ts
    ├── api-key-auth.ts
    └── session-auth.ts

Usage:

// CRUD operations
import { EntityApiClient } from '@/core/lib/api/entities'

const tasks = await EntityApiClient.list('tasks', {
  filters: { status: 'in_progress' },
  page: 1,
  limit: 20
})

// Dual authentication
import { authenticateRequest } from '@/core/lib/api/auth/dual-auth'

const authResult = await authenticateRequest(request)
if (!authResult.authenticated) {
  return createAuthError('Unauthorized', 401)
}

// Response formatting
import { createApiResponse, createPaginatedResponse } from '@/core/lib/api/helpers'

return createPaginatedResponse(data, {
  page: 1,
  limit: 20,
  total: 100
})

---

3. Services Module (services/)

Purpose: Business logic services with RLS support.

Key Files:

services/
├── user.service.ts                 # User CRUD
├── meta.service.ts                 # Metadata operations
├── user-flags.service.ts           # Feature flags
├── transactional-meta.service.ts   # Transactional metadata
└── api-key.service.ts              # API key management

Usage:

// User service
import { UserService } from '@/core/lib/services/user.service'

const user = await UserService.getUser(userId)
await UserService.updateUser(userId, { name: 'New Name' })

// Metadata service
import { MetaService } from '@/core/lib/services/meta.service'

await MetaService.createMeta({
  entityId: 'task_123',
  key: 'priority',
  value: 'high',
  userId: 'user_456'
})

const metadata = await MetaService.getMergedMeta('task_123', 'user_456')

// Feature flags
import { UserFlagsService } from '@/core/lib/services/user-flags.service'

const hasFeature = await UserFlagsService.hasFlag(userId, 'beta_features')

---

4. Auth Module (auth/)

Purpose: Better Auth configuration and authentication utilities.

Key Files:

auth/
├── auth.ts                  # Better Auth instance
├── auth-client.ts           # Client-side auth
└── dual-auth.ts             # Dual authentication handler

Usage:

// Server-side session
import { auth } from '@/core/lib/auth/auth'

const session = await auth.api.getSession({
  headers: request.headers
})

// Client-side auth
import { authClient } from '@/core/lib/auth/auth-client'

const { data, error } = await authClient.signIn.email({
  email: 'user@example.com',
  password: 'password'
})

---

5. Entities Module (entities/)

Purpose: Entity type definitions and core entities.

Key Files:

entities/
├── types.ts                 # Type definitions
└── core/                    # Core entities
    ├── users/
    └── api-keys/

Usage:

// Import types
import type { EntityConfig, FieldDefinition } from '@/core/lib/entities/types'

// Access core entities via registry (not direct import)
import { ENTITY_REGISTRY } from '@/core/lib/registries/entity-registry'

const userConfig = ENTITY_REGISTRY.users // isCore: true

---

Supporting Modules

6. Config Module (config/)

Purpose: Centralized configuration.

Files:

• app.config.ts - Application settings
• dashboard.config.ts - Dashboard layout
• icon-map.ts - Icon registry
• protected-paths.ts - Route protection

Usage:

import { appConfig } from '@/core/lib/config/app.config'
import { PROTECTED_PATHS } from '@/core/lib/config/protected-paths'
import { iconMap } from '@/core/lib/config/icon-map'

---

7. I18n Module (i18n/)

Purpose: Internationalization utilities.

Files:

• locale.ts - Locale configuration
• i18n-utils.ts - Translation utilities
• locale-client.ts - Client locale management

Usage:

import { getLocale } from '@/core/lib/i18n/locale'
import { locales, defaultLocale } from '@/core/lib/i18n/locale'

---

8. Theme Module (theme/)

Purpose: Theme loading and CSS generation.

Files:

• theme-loader.ts - Theme loading
• css-variables.ts - CSS variable generation

Usage:

import { THEME_REGISTRY } from '@/core/lib/registries/theme-registry'
import { generateCSSVariables } from '@/core/lib/theme/css-variables'

---

9. Plugins Module (plugins/)

Purpose: Plugin lifecycle management.

Files:

• plugin-loader.ts - Plugin loading
• hook-system.ts - Lifecycle hooks

Usage:

import { PLUGIN_REGISTRY } from '@/core/lib/registries/plugin-registry'
import { executePluginHook } from '@/core/lib/plugins/hook-system'

---

10. Security Module (security/)

Purpose: Security utilities and RLS helpers.

Files:

• rls-helpers.ts - Row-Level Security
• validation.ts - Input validation
• csrf.ts - CSRF protection

Usage:

import { queryWithRLS } from '@/core/lib/security/rls-helpers'

const tasks = await queryWithRLS<Task>(
  'SELECT * FROM tasks WHERE status = $1',
  ['in_progress'],
  userId // Sets RLS context
)

---

11. Email Module (email/)

Purpose: Email service abstraction.

Files:

• email-factory.ts - Provider selection
• email-service.ts - Sending interface
• templates/ - Email templates

Usage:

import { emailService } from '@/core/lib/email/email-service'

await emailService.send({
  to: 'user@example.com',
  subject: 'Welcome!',
  template: 'welcome',
  data: { name: 'John' }
})

---

12. Utils Module (utils/)

Purpose: General utilities.

Files:

• formatters.ts - Data formatting
• date-utils.ts - Date operations
• string-utils.ts - String helpers
• search-highlighting.ts - Search utilities

Usage:

import { formatCurrency, formatDate } from '@/core/lib/utils/formatters'

const price = formatCurrency(1234.56, 'USD') // "$1,234.56"

---

13. OAuth Module (oauth/)

Purpose: OAuth provider integrations.

Files:

• google.ts - Google OAuth
• github.ts - GitHub OAuth
• strategies/ - OAuth strategies

---

14. Docs Module (docs/)

Purpose: Documentation utilities.

Files:

• docs-loader.ts - Documentation loading
• docs-parser.ts - Markdown parsing
• docs-search.ts - Search functionality

---

Import Best Practices

✅ Correct Patterns

// Registries
import { ENTITY_REGISTRY } from '@/core/lib/registries/entity-registry'
import { THEME_REGISTRY } from '@/core/lib/registries/theme-registry'

// Services
import { UserService } from '@/core/lib/services/user.service'
import { MetaService } from '@/core/lib/services/meta.service'

// API
import { EntityApiClient } from '@/core/lib/api/entities'
import { authenticateRequest } from '@/core/lib/api/auth/dual-auth'

// Auth
import { auth } from '@/core/lib/auth/auth'

// Types
import type { EntityConfig } from '@/core/lib/entities/types'

❌ Incorrect Patterns

// ❌ Never import from @/contents
import { config } from '@/contents/themes/default/theme.config'

// ❌ Never edit registry files
import { generateRegistry } from '@/core/lib/registries/entity-registry'

// ❌ Never use dynamic imports for config
const config = await import(`@/contents/${path}`)

---

Module Selection Guide

Creating API Endpoints: → Use: api/, services/, registries/, auth/

Working with Entities: → Use: entities/, registries/entity-registry, services/

Authentication: → Use: auth/, api/auth/, services/user.service

Themes: → Use: theme/, registries/theme-registry

Plugins: → Use: plugins/, registries/plugin-registry

Internationalization: → Use: i18n/, registries/translation-registry

Emails: → Use: email/

Security: → Use: security/, auth/

Data Formatting: → Use: utils/

---

Common Patterns

Pattern 1: Protected API Route

import { authenticateRequest } from '@/core/lib/api/auth/dual-auth'
import { ENTITY_REGISTRY } from '@/core/lib/registries/entity-registry'
import { EntityApiClient } from '@/core/lib/api/entities'

export async function GET(request: NextRequest) {
  const authResult = await authenticateRequest(request)
  if (!authResult.authenticated) {
    return createAuthError('Unauthorized', 401)
  }

  const tasks = await EntityApiClient.list('tasks', {
    userId: authResult.user.id
  })

  return createApiResponse({ data: tasks })
}

Pattern 2: Server Component with Registry

import { ENTITY_REGISTRY } from '@/core/lib/registries/entity-registry'

export default async function EntityPage({ params }) {
  const entityConfig = ENTITY_REGISTRY[params.entity]

  if (!entityConfig) {
    notFound()
  }

  return <div>{/* Render entity UI */}</div>
}

Pattern 3: Service Layer Usage

import { UserService } from '@/core/lib/services/user.service'
import { MetaService } from '@/core/lib/services/meta.service'

export async function updateUserPreferences(userId, preferences) {
  const user = await UserService.getUser(userId)

  await MetaService.createMeta({
    entityId: userId,
    key: 'preferences',
    value: JSON.stringify(preferences),
    userId
  })

  return { success: true }
}

---

Summary

Core Modules:

• registries/ - Auto-generated (NEVER edit manually)
• api/ - CRUD generation, authentication, caching
• services/ - Business logic with RLS
• auth/ - Better Auth integration
• entities/ - Type definitions

Supporting Modules:

• config/ - App-wide settings
• i18n/ - Internationalization
• theme/ - Theme utilities
• plugins/ - Plugin lifecycle
• security/ - RLS, validation
• email/ - Transactional emails
• utils/ - General utilities

Key Principles:

• Always use registries (never import from @/contents)
• Use services for business logic (includes RLS)
• Never edit auto-generated files
• Follow import best practices

Next: Directory Structure

---

Last Updated: 2025-11-19 Version: 1.0.0 Status: Complete