# monicahq/monica architecture

> Architecture diagram of the GitHub repository monicahq/monica, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monicahq/monica
- Repository: https://github.com/monicahq/monica

## Overview

Monica is a self-hosted personal relationship manager for recording information about family and friends. Users manage contacts and their many details, organize them in shared vaults, and track interactions, reminders, tasks, and diary entries. The sampled contact controller delegates contact operations to services; the broader domain directories also cover these README-documented features. The graph reflects that documented product scope, while edges are limited to relationships visible in the excerpts or source index; several feature implementations were not sampled.

Main entry points: [`app/Models/Contact.php`](https://github.com/monicahq/monica/blob/main/app/Models/Contact.php) (Contact record), [`app/Domains/Contact/ManageContact/Services`](https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageContact/Services) (Contact operations), [`app/Models/Vault.php`](https://github.com/monicahq/monica/blob/main/app/Models/Vault.php) (Vault), [`app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php`](https://github.com/monicahq/monica/blob/main/app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php) (Contact workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web and identity"]
  node_web["Web controller<br/>[Controller.php]"]
  node_social_auth["Social sign-in"]
end

subgraph group_contacts["Contact records"]
  node_contact_web["Contact workflow"]
  node_contact_ops["Contact operations"]
  node_contact[("Contact record<br/>[Contact.php]")]
  node_group[("Contact groups<br/>[Group.php]")]
end

subgraph group_activities["Life tracking"]
  node_contact_feed[("Interaction feed")]
  node_reminders["Reminders"]
  node_tasks["Tasks"]
  node_journal["Diary<br/>[PostController.php]"]
  node_documents["Photos and files<br/>[UploadFile.php]"]
  node_file[("File metadata<br/>[File.php]")]
end

subgraph group_sharing["Vaults and settings"]
  node_account[("Account<br/>[Account.php]")]
  node_user[("User<br/>[User.php]")]
  node_vault[("Vault<br/>[Vault.php]")]
  node_vault_view["Vault overview"]
  node_settings["Personalization"]
  node_base_service["Service validation<br/>[BaseService.php]"]
  node_service_interface["Service contract"]
  node_gender[("Custom genders<br/>[Gender.php]")]
  node_pronoun[("Pronouns<br/>[Pronoun.php]")]
  node_template[("Contact templates<br/>[Template.php]")]
end

subgraph group_interchange["DAV synchronization"]
  node_dav_client["DAV client<br/>[DavClient.php]"]
  node_dav_sync["Address book sync"]
  node_dav_resources["CardDAV and CalDAV"]
end

node_person(("Monica user"))
node_dav_server["DAV server"]

node_person -->|"manages contacts"| node_contact_web
node_contact_web -->|"extends"| node_web
node_contact_web -->|"calls"| node_contact_ops
node_contact_web -->|"reads"| node_contact
node_contact_ops -->|"reads and writes"| node_contact
node_contact_ops -->|"inherits"| node_base_service
node_contact_ops -->|"implements"| node_service_interface
node_contact_ops -->|"creates feed item"| node_contact_feed
node_contact -->|"references"| node_gender
node_contact -->|"references"| node_pronoun
node_contact -->|"references"| node_template
node_contact -->|"relates to"| node_group
node_person -->|"organizes records"| node_vault_view
node_vault_view -->|"queries"| node_vault
node_user -->|"shares access"| node_vault
node_account -->|"owns users"| node_user
node_account -->|"owns vaults"| node_vault
node_vault -->|"contains contacts"| node_contact
node_vault -->|"contains files"| node_file
node_person -->|"sets reminders"| node_reminders
node_person -->|"manages tasks"| node_tasks
node_person -->|"records diary"| node_journal
node_person -->|"uploads media"| node_documents
node_documents -->|"creates metadata"| node_file
node_person -->|"personalizes fields"| node_settings
node_person -->|"signs in"| node_social_auth
node_social_auth -->|"authenticates"| node_user
node_dav_sync -.->|"uses client"| node_dav_client
node_dav_client -.->|"exchanges DAV data"| node_dav_server
node_dav_resources -->|"imports and exports"| node_contact

click node_web "https://github.com/monicahq/monica/blob/main/app/Http/Controllers/Controller.php"
click node_social_auth "https://github.com/monicahq/monica/blob/main/app/Http/Controllers/Auth/SocialiteCallbackController.php"
click node_contact_web "https://github.com/monicahq/monica/blob/main/app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php"
click node_contact_ops "https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageContact/Services"
click node_contact "https://github.com/monicahq/monica/blob/main/app/Models/Contact.php"
click node_group "https://github.com/monicahq/monica/blob/main/app/Models/Group.php"
click node_contact_feed "https://github.com/monicahq/monica/blob/main/app/Models/ContactFeedItem.php"
click node_reminders "https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageReminders"
click node_tasks "https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageTasks"
click node_journal "https://github.com/monicahq/monica/blob/main/app/Domains/Vault/ManageJournals/Web/Controllers/PostController.php"
click node_documents "https://github.com/monicahq/monica/blob/main/app/Domains/Contact/ManageDocuments/Services/UploadFile.php"
click node_file "https://github.com/monicahq/monica/blob/main/app/Models/File.php"
click node_account "https://github.com/monicahq/monica/blob/main/app/Models/Account.php"
click node_user "https://github.com/monicahq/monica/blob/main/app/Models/User.php"
click node_vault "https://github.com/monicahq/monica/blob/main/app/Models/Vault.php"
click node_vault_view "https://github.com/monicahq/monica/blob/main/app/Domains/Vault/ManageVault/Web/ViewHelpers/VaultIndexViewHelper.php"
click node_settings "https://github.com/monicahq/monica/tree/main/app/Domains/Settings"
click node_base_service "https://github.com/monicahq/monica/blob/main/app/Services/BaseService.php"
click node_service_interface "https://github.com/monicahq/monica/blob/main/app/Interfaces/ServiceInterface.php"
click node_gender "https://github.com/monicahq/monica/blob/main/app/Models/Gender.php"
click node_pronoun "https://github.com/monicahq/monica/blob/main/app/Models/Pronoun.php"
click node_template "https://github.com/monicahq/monica/blob/main/app/Models/Template.php"
click node_dav_client "https://github.com/monicahq/monica/blob/main/app/Domains/Contact/DavClient/Services/Utils/Dav/DavClient.php"
click node_dav_sync "https://github.com/monicahq/monica/blob/main/app/Domains/Contact/DavClient/Services/SynchronizeAddressBook.php"
click node_dav_resources "https://github.com/monicahq/monica/tree/main/app/Domains/Contact/Dav/Web/Backend"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_social_auth,node_person toneBlue
class node_contact_web,node_contact_ops,node_contact,node_group toneAmber
class node_contact_feed,node_reminders,node_tasks,node_journal,node_documents,node_file,node_dav_server toneMint
class node_account,node_user,node_vault,node_vault_view,node_settings,node_base_service,node_service_interface,node_gender,node_pronoun,node_template toneRose
class node_dav_client,node_dav_sync,node_dav_resources toneIndigo
```

## Components

### Web and identity

- [Web controller](https://github.com/monicahq/monica/blob/main/app/Http/Controllers/Controller.php): `app/Http/Controllers/Controller.php`
- [Social sign-in](https://github.com/monicahq/monica/blob/main/app/Http/Controllers/Auth/SocialiteCallbackController.php): `app/Http/Controllers/Auth/SocialiteCallbackController.php`

### Contact records

- [Contact workflow](https://github.com/monicahq/monica/blob/main/app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php): `app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php`
- [Contact operations](https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageContact/Services): `app/Domains/Contact/ManageContact/Services`
- [Contact record](https://github.com/monicahq/monica/blob/main/app/Models/Contact.php): `app/Models/Contact.php`
- [Contact groups](https://github.com/monicahq/monica/blob/main/app/Models/Group.php): `app/Models/Group.php`

### Life tracking

- [Interaction feed](https://github.com/monicahq/monica/blob/main/app/Models/ContactFeedItem.php): `app/Models/ContactFeedItem.php`
- [Reminders](https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageReminders): `app/Domains/Contact/ManageReminders`
- [Tasks](https://github.com/monicahq/monica/tree/main/app/Domains/Contact/ManageTasks): `app/Domains/Contact/ManageTasks`
- [Diary](https://github.com/monicahq/monica/blob/main/app/Domains/Vault/ManageJournals/Web/Controllers/PostController.php): `app/Domains/Vault/ManageJournals/Web/Controllers/PostController.php`
- [Photos and files](https://github.com/monicahq/monica/blob/main/app/Domains/Contact/ManageDocuments/Services/UploadFile.php): `app/Domains/Contact/ManageDocuments/Services/UploadFile.php`
- [File metadata](https://github.com/monicahq/monica/blob/main/app/Models/File.php): `app/Models/File.php`

### Vaults and settings

- [Account](https://github.com/monicahq/monica/blob/main/app/Models/Account.php): `app/Models/Account.php`
- [User](https://github.com/monicahq/monica/blob/main/app/Models/User.php): `app/Models/User.php`
- [Vault](https://github.com/monicahq/monica/blob/main/app/Models/Vault.php): `app/Models/Vault.php`
- [Vault overview](https://github.com/monicahq/monica/blob/main/app/Domains/Vault/ManageVault/Web/ViewHelpers/VaultIndexViewHelper.php): `app/Domains/Vault/ManageVault/Web/ViewHelpers/VaultIndexViewHelper.php`
- [Personalization](https://github.com/monicahq/monica/tree/main/app/Domains/Settings): `app/Domains/Settings`
- [Service validation](https://github.com/monicahq/monica/blob/main/app/Services/BaseService.php): `app/Services/BaseService.php`
- [Service contract](https://github.com/monicahq/monica/blob/main/app/Interfaces/ServiceInterface.php): `app/Interfaces/ServiceInterface.php`
- [Custom genders](https://github.com/monicahq/monica/blob/main/app/Models/Gender.php): `app/Models/Gender.php`
- [Pronouns](https://github.com/monicahq/monica/blob/main/app/Models/Pronoun.php): `app/Models/Pronoun.php`
- [Contact templates](https://github.com/monicahq/monica/blob/main/app/Models/Template.php): `app/Models/Template.php`

### DAV synchronization

- [DAV client](https://github.com/monicahq/monica/blob/main/app/Domains/Contact/DavClient/Services/Utils/Dav/DavClient.php): `app/Domains/Contact/DavClient/Services/Utils/Dav/DavClient.php`
- [Address book sync](https://github.com/monicahq/monica/blob/main/app/Domains/Contact/DavClient/Services/SynchronizeAddressBook.php): `app/Domains/Contact/DavClient/Services/SynchronizeAddressBook.php`
- [CardDAV and CalDAV](https://github.com/monicahq/monica/tree/main/app/Domains/Contact/Dav/Web/Backend): `app/Domains/Contact/Dav/Web/Backend`

### Other components

- **Monica user**
- **DAV server**

## Connections

- Monica user → Contact workflow: manages contacts (evidence: `README.md`)
- Contact workflow → Web controller: extends (evidence: `app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php`)
- Contact workflow → Contact operations: calls (evidence: `app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php`)
- Contact workflow → Contact record: reads (evidence: `app/Domains/Contact/ManageContact/Web/Controllers/ContactController.php`)
- Contact operations → Contact record: reads and writes (evidence: `app/Domains/Contact/ManageContact/Services/CreateContact.php`)
- Contact operations → Service validation: inherits (evidence: `app/Domains/Contact/ManageContact/Services/CreateContact.php`)
- Contact operations → Service contract: implements (evidence: `app/Domains/Contact/ManageContact/Services/CreateContact.php`)
- Contact operations → Interaction feed: creates feed item (evidence: `app/Domains/Contact/ManageContact/Services/CreateContact.php`)
- Contact record → Custom genders: references (evidence: `app/Models/Contact.php`)
- Contact record → Pronouns: references (evidence: `app/Models/Contact.php`)
- Contact record → Contact templates: references (evidence: `app/Models/Contact.php`)
- Contact record → Contact groups: relates to (evidence: `app/Models/Contact.php`)
- Monica user → Vault overview: organizes records (evidence: `README.md`)
- Vault overview → Vault: queries (evidence: `app/Domains/Vault/ManageVault/Web/ViewHelpers/VaultIndexViewHelper.php`)
- User → Vault: shares access (evidence: `app/Models/User.php`)
- Account → User: owns users (evidence: `app/Models/Account.php`)
- Account → Vault: owns vaults (evidence: `app/Models/Account.php`)
- Vault → Contact record: contains contacts (evidence: `app/Models/Vault.php`)
- Vault → File metadata: contains files (evidence: `app/Models/Vault.php`)
- Monica user → Reminders: sets reminders (evidence: `README.md`)
- Monica user → Tasks: manages tasks (evidence: `README.md`)
- Monica user → Diary: records diary (evidence: `README.md`)
- Monica user → Photos and files: uploads media (evidence: `README.md`)
- Photos and files → File metadata: creates metadata (evidence: `app/Models/File.php`)
- Monica user → Personalization: personalizes fields (evidence: `README.md`)
- Monica user → Social sign-in: signs in (evidence: `app/Http/Controllers/Auth/SocialiteCallbackController.php`)
- Social sign-in → User: authenticates
- Address book sync → DAV client: uses client
- DAV client → DAV server: exchanges DAV data
- CardDAV and CalDAV → Contact record: imports and exports (evidence: `app/Models/Contact.php`)
