# nextcloud/contacts architecture

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

- Interactive diagram: https://gitdiagram.com/nextcloud/contacts
- Repository: https://github.com/nextcloud/contacts

## Overview

Nextcloud Contacts is a vCard 3.0/4.0 contacts app for editing and syncing contacts, address books, and related collaboration features. Users enter through the routed Vue app, browse or edit contacts, and manage address books or imports; optional branches cover team views, social-profile enrichment, and federated OCM invitations. The frontend uses Vuex stores and contact models, while PHP controllers and services implement server-side features. The README identifies CardDAV as a backend responsibility outside this repository; some capability links below are documented rather than verified in sampled implementation.

Main entry points: [`src/views/Contacts.vue`](https://github.com/nextcloud/contacts/blob/main/src/views/Contacts.vue) (Contacts view), [`src/main.js`](https://github.com/nextcloud/contacts/blob/main/src/main.js) (Vue app), [`src/store/addressbooks.js`](https://github.com/nextcloud/contacts/blob/main/src/store/addressbooks.js) (Address books), [`src/store/index.js`](https://github.com/nextcloud/contacts/blob/main/src/store/index.js) (Vuex store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Contacts interface"]
  node_app["Vue app<br/>[main.js]"]
  node_router["App routes<br/>[index.js]"]
  node_contacts_view["Contacts view<br/>[Contacts.vue]"]
  node_navigation["Root navigation<br/>[RootNavigation.vue]"]
  node_contact_details["Contact details<br/>[ContactDetails.vue]"]
  node_import_view["Contact import<br/>[ImportView.vue]"]
end

subgraph group_contactdata["Contact data"]
  node_store["Vuex store<br/>[index.js]"]
  node_addressbooks["Address books<br/>[addressbooks.js]"]
  node_contact_model["vCard contact model<br/>[contact.js]"]
end

subgraph group_collaboration["Collaboration"]
  node_circles_view["Team circles<br/>[CircleContent.vue]"]
  node_chart_view["Contact charts<br/>[ChartContent.vue]"]
  node_ocm_view["Federated invites"]
end

subgraph group_server["Server features"]
  node_ocm_controller["Invite endpoints"]
  node_invite_service["Invite service"]
  node_invite_mapper[("Invite persistence")]
  node_invite_record["Invite record"]
  node_social_controller["Social API"]
  node_social_service["Social profiles"]
end

node_user(("Contacts user"))
node_carddav["CardDAV backend"]
node_nextcloud["Nextcloud platform"]

node_user -->|"opens"| node_app
node_app -->|"registers"| node_router
node_app -->|"registers"| node_store
node_router -->|"routes to"| node_contacts_view
node_contacts_view -->|"renders"| node_navigation
node_contacts_view -->|"dispatches"| node_store
node_contacts_view -->|"renders"| node_contact_details
node_store -->|"registers"| node_addressbooks
node_addressbooks -->|"uses"| node_contact_model
node_contact_details -->|"uses"| node_contact_model
node_addressbooks -.->|"syncs with"| node_carddav
node_contacts_view -->|"opens"| node_import_view
node_contacts_view -->|"renders"| node_circles_view
node_contacts_view -->|"renders"| node_chart_view
node_contacts_view -->|"renders"| node_ocm_view
node_contacts_view -->|"accepts invite"| node_ocm_controller
node_ocm_controller -->|"delegates to"| node_invite_service
node_invite_service -->|"reads and writes"| node_invite_mapper
node_invite_mapper -->|"maps"| node_invite_record
node_social_controller -->|"delegates to"| node_social_service
node_nextcloud -->|"hosts"| node_app
node_nextcloud -->|"provides"| node_carddav

click node_app "https://github.com/nextcloud/contacts/blob/main/src/main.js"
click node_router "https://github.com/nextcloud/contacts/blob/main/src/router/index.js"
click node_contacts_view "https://github.com/nextcloud/contacts/blob/main/src/views/Contacts.vue"
click node_navigation "https://github.com/nextcloud/contacts/blob/main/src/components/AppNavigation/RootNavigation.vue"
click node_contact_details "https://github.com/nextcloud/contacts/blob/main/src/components/ContactDetails.vue"
click node_import_view "https://github.com/nextcloud/contacts/blob/main/src/views/Processing/ImportView.vue"
click node_store "https://github.com/nextcloud/contacts/blob/main/src/store/index.js"
click node_addressbooks "https://github.com/nextcloud/contacts/blob/main/src/store/addressbooks.js"
click node_contact_model "https://github.com/nextcloud/contacts/blob/main/src/models/contact.js"
click node_circles_view "https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/CircleContent.vue"
click node_chart_view "https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/ChartContent.vue"
click node_ocm_view "https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/OcmInvitesContent.vue"
click node_ocm_controller "https://github.com/nextcloud/contacts/blob/main/lib/Controller/FederatedInvitesController.php"
click node_invite_service "https://github.com/nextcloud/contacts/blob/main/lib/Service/FederatedInvitesService.php"
click node_invite_mapper "https://github.com/nextcloud/contacts/blob/main/lib/Db/FederatedInviteMapper.php"
click node_invite_record "https://github.com/nextcloud/contacts/blob/main/lib/Db/FederatedInvite.php"
click node_social_controller "https://github.com/nextcloud/contacts/blob/main/lib/Controller/SocialApiController.php"
click node_social_service "https://github.com/nextcloud/contacts/blob/main/lib/Service/SocialApiService.php"

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_app,node_router,node_contacts_view,node_navigation,node_contact_details,node_import_view,node_user toneBlue
class node_store,node_addressbooks,node_contact_model toneAmber
class node_circles_view,node_chart_view,node_ocm_view toneMint
class node_ocm_controller,node_invite_service,node_invite_mapper,node_invite_record,node_social_controller,node_social_service toneRose
class node_carddav,node_nextcloud toneIndigo
```

## Components

### Contacts interface

- [Vue app](https://github.com/nextcloud/contacts/blob/main/src/main.js): `src/main.js`
- [App routes](https://github.com/nextcloud/contacts/blob/main/src/router/index.js): `src/router/index.js`
- [Contacts view](https://github.com/nextcloud/contacts/blob/main/src/views/Contacts.vue): `src/views/Contacts.vue`
- [Root navigation](https://github.com/nextcloud/contacts/blob/main/src/components/AppNavigation/RootNavigation.vue): `src/components/AppNavigation/RootNavigation.vue`
- [Contact details](https://github.com/nextcloud/contacts/blob/main/src/components/ContactDetails.vue): `src/components/ContactDetails.vue`
- [Contact import](https://github.com/nextcloud/contacts/blob/main/src/views/Processing/ImportView.vue): `src/views/Processing/ImportView.vue`

### Contact data

- [Vuex store](https://github.com/nextcloud/contacts/blob/main/src/store/index.js): `src/store/index.js`
- [Address books](https://github.com/nextcloud/contacts/blob/main/src/store/addressbooks.js): `src/store/addressbooks.js`
- [vCard contact model](https://github.com/nextcloud/contacts/blob/main/src/models/contact.js): `src/models/contact.js`

### Collaboration

- [Team circles](https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/CircleContent.vue): `src/components/AppContent/CircleContent.vue`
- [Contact charts](https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/ChartContent.vue): `src/components/AppContent/ChartContent.vue`
- [Federated invites](https://github.com/nextcloud/contacts/blob/main/src/components/AppContent/OcmInvitesContent.vue): `src/components/AppContent/OcmInvitesContent.vue`

### Server features

- [Invite endpoints](https://github.com/nextcloud/contacts/blob/main/lib/Controller/FederatedInvitesController.php): `lib/Controller/FederatedInvitesController.php`
- [Invite service](https://github.com/nextcloud/contacts/blob/main/lib/Service/FederatedInvitesService.php): `lib/Service/FederatedInvitesService.php`
- [Invite persistence](https://github.com/nextcloud/contacts/blob/main/lib/Db/FederatedInviteMapper.php): `lib/Db/FederatedInviteMapper.php`
- [Invite record](https://github.com/nextcloud/contacts/blob/main/lib/Db/FederatedInvite.php): `lib/Db/FederatedInvite.php`
- [Social API](https://github.com/nextcloud/contacts/blob/main/lib/Controller/SocialApiController.php): `lib/Controller/SocialApiController.php`
- [Social profiles](https://github.com/nextcloud/contacts/blob/main/lib/Service/SocialApiService.php): `lib/Service/SocialApiService.php`

### Other components

- **Contacts user**
- **CardDAV backend**
- **Nextcloud platform**

## Connections

- Contacts user → Vue app: opens
- Vue app → App routes: registers (evidence: `src/main.js`)
- Vue app → Vuex store: registers (evidence: `src/main.js`)
- App routes → Contacts view: routes to (evidence: `src/router/index.js`)
- Contacts view → Root navigation: renders (evidence: `src/views/Contacts.vue`)
- Contacts view → Vuex store: dispatches (evidence: `src/views/Contacts.vue`)
- Contacts view → Contact details: renders (evidence: `src/components/ContactDetails.vue`)
- Vuex store → Address books: registers (evidence: `src/store/index.js`)
- Address books → vCard contact model: uses (evidence: `src/store/addressbooks.js`)
- Contact details → vCard contact model: uses (evidence: `src/components/ContactDetails.vue`)
- Address books → CardDAV backend: syncs with
- Contacts view → Contact import: opens (evidence: `src/views/Contacts.vue`)
- Contacts view → Team circles: renders (evidence: `src/views/Contacts.vue`)
- Contacts view → Contact charts: renders (evidence: `src/views/Contacts.vue`)
- Contacts view → Federated invites: renders (evidence: `src/views/Contacts.vue`)
- Contacts view → Invite endpoints: accepts invite (evidence: `src/views/Contacts.vue`)
- Invite endpoints → Invite service: delegates to (evidence: `lib/Controller/FederatedInvitesController.php`)
- Invite service → Invite persistence: reads and writes (evidence: `lib/Service/FederatedInvitesService.php`)
- Invite persistence → Invite record: maps (evidence: `lib/Db/FederatedInviteMapper.php`)
- Social API → Social profiles: delegates to (evidence: `lib/Controller/SocialApiController.php`)
- Nextcloud platform → Vue app: hosts
- Nextcloud platform → CardDAV backend: provides
