This section provides technical reference material for the Immich codebase. It covers the OpenAPI specification, environment variables, database schema, internationalization, and API endpoint groups. For deployment guidance, see Deployment Guide. For developer setup and build processes, see Development Guide.
All Immich components share a synchronized version number. The system follows semantic versioning, where breaking changes are intended to be limited to major releases.
| Component | Package Name | Runtime | Primary Entry / Config |
|---|---|---|---|
| Server | immich | Node.js / NestJS | server/src/main.ts1-194 |
| Web | immich-web | Node.js / SvelteKit | web/ |
| Mobile | immich_mobile | Flutter / Dart | mobile/ |
| Machine Learning | immich-ml | Python / FastAPI | machine-learning/ |
| Documentation | immich-docs | Docusaurus | docs/docusaurus.config.js1-231 |
Sources: docs/docusaurus.config.js7-13 server/src/main.ts1-194
The following diagram maps human-readable component names to their code-level package and module identities, specifically highlighting how the server manages different worker types.
Component and Module Identity Map
Sources: docs/docs/guides/database-queries.md8 server/src/main.ts1-50
The OpenAPI specification is the authoritative contract between the server and all clients. It is used to generate the Dart SDK consumed by the mobile application. For full details, see OpenAPI Specification and API Endpoints.
OpenAPI Spec Generation and Consumption
Sources: server/src/dtos/asset-response.dto.ts25-119 mobile/openapi/lib/model/asset_response_dto.dart13-48
Server configuration is primarily managed through environment variables. These variables control everything from database connection strings to which workers are active. For a full reference, see Environment Variables.
| Variable Category | Code Entity | Description |
|---|---|---|
| Database | DB_DATABASE_NAME | The name of the PostgreSQL database. docs/docs/guides/database-queries.md10 |
| Authentication | OAuth | Configuration for external identity providers. docs/docs/administration/system-settings.md13-15 |
| Machine Learning | MACHINE_LEARNING_URL | The endpoint for the ML service. docs/docs/administration/system-settings.md101-103 |
| Logging | LOG_LEVEL | Controls verbosity of the system logs. docs/docs/administration/system-settings.md94 |
Sources: docs/docs/guides/database-queries.md10 docs/docs/administration/system-settings.md9-120
Immich utilizes PostgreSQL for metadata storage and specialized extensions for vector similarity search. The system uses these for Smart Search (CLIP) and Face Recognition. For full schema documentation, see Database Schema.
| Table Name | Description | Key Columns |
|---|---|---|
asset | Primary asset metadata | id, checksum, originalPath, type docs/docs/guides/database-queries.md21-58 |
asset_exif | Extracted EXIF/XMP data | assetId, description, fileSizeInByte docs/docs/guides/database-queries.md67-86 |
person | Identified individuals | id, name docs/docs/guides/database-queries.md131-135 |
system_metadata | System configuration | key, value docs/docs/guides/database-queries.md141-143 |
Sources: docs/docs/guides/database-queries.md13-165 server/src/dtos/asset-response.dto.ts3-18
The project supports multiple languages across the web and mobile platforms. The i18n system allows for community-driven translations, managed via localization files in the repository. For full documentation on adding or updating translations, see Internationalization.
Sources: docs/docusaurus.config.js23-26
| Page | Content |
|---|---|
| OpenAPI Specification | Reference for the complete OpenAPI specification including all endpoints, schemas, and examples. |
| Environment Variables | Comprehensive reference of all environment variables for server, ML service, and configuration. |
| Database Schema | Documentation of the PostgreSQL database schema, tables, relationships, and vector extensions. |
| Internationalization | Explanation of the i18n system, translation workflow, and language support. |
| API Endpoints | Quick reference of key API endpoints with examples and common use cases. |
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.