mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
5a2181bcec
# Which Problems Are Solved In many cases IAM was used where instance was meant. # How the Problems Are Solved - Rename wrong usage of IAM to instance all over the code base. - Add an agents.md which explains the terms used in Zitadel's architecture. # Additional Context - closes #11280 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: muhlemmer <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: Marco A. <[email protected]>
3.7 KiB
3.7 KiB
ZITADEL Domain & Multi-Tenancy Logic
1. Hierarchy & Ownership
ZITADEL follows a strict hierarchical containment model. When generating code, logic, or translations, adhere to this structure:
- System (Installation): The entire ZITADEL deployment. Global settings are applied through runtime configuration files or environment variables. See
cmd/defaults.yaml. - Instance (The "Identity System"):
- Definition: A logical partition/virtual tenant. It is a "System inside a System."
- Isolation: Data and configurations are strictly isolated between instances.
- Translation Rule: NEVER translate as "Example" or "Case." Use technical terms like "Tenant," "Environment," or the local equivalent of "Logical System Entity."
- Organization: A group within an Instance. It owns Users, Projects, and Roles.
- Project: A collection of Applications and Auth Policies within an Org.
2. Permission Scoping (The "Administrative" Context)
- System User: Manages the entire Installation and creates Instances over the system API.
- Instance Admin: Manages Instance-wide policies (Password complexity, Identity Providers, Organizations).
- Organization Admin: Manages users and access within a specific Organization.
3. Language & Tone Guidelines
- Avoid Ambiguity: When referring to an 'Instance', the context is always infrastructure/tenancy.
- Technical Precision: In UI strings, prefer clarity over brevity if "Instance" is likely to be misinterpreted in the target language.
4. Technical Glossary & Localization Mapping
| Language | Technical Term (SaaS/Cloud) | Why this term? | "Avoid this (The ""Example"" Trap)" |
|---|---|---|---|
| Chinese (Simplified) | 实例 (Shílì) | Standard for a cloud resource/entity. | 例子 (Lìzi) |
| Japanese | インスタンス (Insutansu) | Katakana transliteration; industry standard. | 例 (Rei) |
| Korean | 인스턴스 (Inseuteonseu) | Hangul transliteration; industry standard. | 예 (Ye) |
| German | Instanz | Matches English but implies a technical occurrence. | Beispiel |
| French | Instance | "Standard but often requires ""de ZITADEL"" for clarity." | Exemple |
| Spanish | Instancia | Technical entity in software architecture. | Ejemplo |
| Portuguese | Instância | Standard technical terminology. | Exemplo |
| Russian | Инстанс (Instans) | Modern SaaS jargon (transliterated). | Пример (Primer) |
Translation Guardrails
If a translation is requested for a language not listed above, follow these priority rules for the word 'Instance':
- Priority 1 (Transliteration): Use the phonetic transliteration into the local script (common in Japanese/Korean/Russian).
- Priority 2 (System Entity): Use a term that implies a "running process" or "logical environment."
- Priority 3 (Tenant): If 'Instance' is ambiguous, use the local word for 'Tenant' (e.g., 租户 in Chinese).
- Strict Ban: NEVER use words that mean "an illustration", "a case", "a sample", or "an example."