# Core Module Index

## Configuration (`src/core/config/`)
- `config-loader.ts` — Load and validate environment variables
- `database.ts` — PostgreSQL connection pool
- `redis.ts` — Redis client, cache helpers, and distributed locking
- `user-context.ts` — User context utilities

### Distributed Lock Service

The `DistributedLockService` in `redis.ts` provides Redis-based distributed locking for preventing duplicate operations across multiple containers (blue-green deployments).

**All scheduled jobs MUST use distributed locking** to prevent duplicate execution when multiple backend containers are running.

```typescript
import { randomUUID } from 'crypto';
import { lockService } from '../core/config/redis';

// Acquire lock (returns false if already held)
const lockKey = 'job:my-scheduled-task';
const lockValue = randomUUID();  // Unique identifier for this execution
const ttlSeconds = 300;          // Auto-release after 5 minutes

const acquired = await lockService.acquireLock(lockKey, ttlSeconds, lockValue);
if (!acquired) {
  // Another container is already running this job
  return;
}

try {
  // Do work...
} finally {
  // Always release the lock
  await lockService.releaseLock(lockKey, lockValue);
}
```

**API:**
| Method | Description |
|--------|-------------|
| `acquireLock(key, ttlSeconds, lockValue)` | Acquire lock atomically (SET NX EX) |
| `releaseLock(key, lockValue)` | Release only if we hold it (Lua script) |
| `isLocked(key)` | Check if lock exists |

## Plugins (`src/core/plugins/`)
- `auth.plugin.ts` — Auth0 JWT via JWKS (@fastify/jwt, get-jwks)
- `error.plugin.ts` — Error handling
- `logging.plugin.ts` — Request logging

## Logging (`src/core/logging/`)
- `logger.ts` — Structured logging (Winston)

## Middleware
- `middleware/user-context.ts` — User ID extraction from JWT

## Storage (`src/core/storage/`)
- `storage.service.ts` — Storage abstraction
- `adapters/filesystem.adapter.ts` — Filesystem storage adapter

