immich-app/immich

Key flows were walked end-to-end. Startup goes through a supervisor that gates on a Postgres advisory lock and maintenance mode, then each worker boots its Nest module which emits AppBootstrap to ordered handlers (database migrations first, then storage, then job discovery). The upload flow traverses guard → multer interceptors → controller → service → DB + queue. Background work is decoupled: jobs land in Redis and are executed by the microservices worker via a JobRun event indirection.

• Startup trace: main() reads argv → Workers.bootstrap() → isMaintenanceMode() (SystemMetadataKey.MaintenanceMode, tolerates missing table via PostgresError 42P01) → waitForFreeLock() (pg_try_advisory_lock loop, 1s poll) → startWorker() per configured ImmichWorker.
  server/src/main.ts#L30-64server/src/main.ts#L66-126
• API worker boot trace: workers/api.ts bootstrap() → configureTelemetry() → NestFactory.create(ApiModule, {routeConflictPolicy duplicate:error, routeResolutionStrategy specificity}) → AppRepository.setCloseFn → configureExpress(app, {ssr: ApiService}) which installs middleware, sirv, swagger, and listens on port 2283.
  server/src/workers/api.ts#L9-24server/src/app.common.ts#L24-95
• Nest module init trace: BaseModule.onModuleInit → telemetryRepository.setup → queueService.setServices(services) → websocketRepository.setAuthFn(authenticate) → eventRepository.setup({services}) → emit('AppBootstrap'); onModuleDestroy emits AppShutdown and tears down telemetry.
  server/src/app.module.ts#L82-102
• Bootstrap ordering is priority-driven: DatabaseService.onBootstrap (priority -200) checks Postgres version range, manages the vector extension (create/update/drop, reindexVectorsIfNeeded), and runs migrations under DatabaseLock.Migrations unless DB_SKIP_MIGRATIONS; StorageService (-195) and JobService (-190) follow, SystemConfig at +100, PluginSync/PluginLoad at +190/+200.
  server/src/services/database.service.ts#L56-120server/src/enum.ts#L801-813
• Job-handler discovery trace: QueueService.onBootstrap (AppBootstrap listener) → jobRepository.setup(services) reflects over every service method, registers those with @OnJob metadata into handlers{}, and throws ImmichStartupError if any JobName value lacks a handler or two handlers claim one job; microservices then startWorkers() and the api worker starts watchWorkers() (30s liveness poll).
  server/src/repositories/job.repository.ts#L40-104server/src/services/queue.service.ts#L78-86
• Upload trace: POST /api/assets → AuthGuard.canActivate (Permission.AssetUpload, sharedLink ok) → AssetUploadInterceptor/FileUploadInterceptor multer writes file → AssetMediaController.uploadAsset → service.uploadAsset → requireAccess + requireQuota → onBeforeLink for livePhotoVideoId → assetRepository.create → upsertMetadata/upsertFile/upsertExif → jobRepository.queue(AssetExtractMetadata) → eventRepository.emit(AssetCreate) → 201 or 200-on-duplicate.
  server/src/controllers/asset-media.controller.ts#L51-90server/src/services/asset-media.service.ts#L125-227
• Metadata extraction trace: microservices bullmq Worker dequeues → eventRepository.emit('JobRun', queueName, job) → JobRepository.run dispatches → MetadataService.handleMetadataExtraction → getExifTags (exiftool) + stat → getDates/getImageDimensions → reverseGeocode if GPS → upsert → downstream AssetMetadataExtracted event queues thumbnails, smart search, and face detection.
  server/src/services/metadata.service.ts#L215-260server/src/repositories/job.repository.ts#L137-160
• Login trace: POST /auth/login → AuthService.login → getConfig(passwordLogin.enabled gate) → userRepository.getByEmail(withPassword) → cryptoRepository.compareBcrypt against user password or LOGIN_DUMMY_HASH for constant-time behavior → createLoginResponse(user, details) issues session + cookies.
  server/src/services/auth.service.ts#L60-77server/src/constants.ts
• Nightly tasks trace: on ConfigInit the non-microservices worker takes DatabaseLock.NightlyJobs, converts config.nightlyTasks.startTime to a cron expression, and registers CronJob.NightlyJobs whose onTick calls handleNightlyJobs(); ConfigUpdate re-schedules it.
  server/src/services/queue.service.ts#L34-76
• Worker crash/restart trace: any worker 'exit' triggers onExit; exitCode ExitCode.AppRestart sets restarting=true and reboots all workers once drained; a non-zero exit otherwise kills the api worker (SIGTERM) if present and exits the supervisor process with the same code.
  server/src/main.ts#L128-162
• Websocket connect trace: socket.io handshake → WebSocketAdapter (redis pub/sub adapter) → authFn registered in BaseModule → AuthService.authenticate with uri '/api/socket.io' → WebsocketConnect event emitted with userId.
  server/src/app.module.ts#L87-93server/src/middleware/websocket.adapter.tsserver/src/repositories/event.repository.ts#L106-107
• ML predict trace: POST /predict → get_entries parses multipart 'entries' JSON into InferenceEntry list splitting with/without model deps → run_inference resolves deps (detection output feeds recognition) → model_cache.get + load() (ONNX fallback if other format unsupported) → model.predict in thread pool → ORJSONResponse.
  machine-learning/immich_ml/main.py#L132-248