# strategic-information-department-cidrz/contact-directory-api architecture

> Architecture diagram of the GitHub repository strategic-information-department-cidrz/contact-directory-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strategic-information-department-cidrz/contact-directory-api
- Repository: https://github.com/strategic-information-department-cidrz/contact-directory-api

## Overview

Contact Directory is an ASP.NET API for maintaining contacts and their geographic and classification lists, with account and administrator management. Users call API controllers; those delegate product operations to application services. The principal directory workflow covers filtered and paged contact retrieval, individual contact maintenance, metrics, and Excel import/export. Separate branches support authentication and account recovery, user administration, lookup/geography maintenance, and legacy-user import. The graph reflects controller calls and the sampled Excel-service dependencies; unsampled service-to-repository wiring is left out.

Main entry points: [`contact-directory.Api/Controllers/AccountController.cs`](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/AccountController.cs) (Account API), [`contact-directory.Application/Services/ContactExcelService.cs`](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ContactExcelService.cs) (Excel transfer), [`contact-directory.Api/Controllers/ContactsController.cs`](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/ContactsController.cs) (Contacts API), [`contact-directory.Application/Services/AccountService.cs`](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/AccountService.cs) (Account operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_contacts_api["Contacts API"]
  node_account_api["Account API"]
  node_auth_api["Auth API<br/>[AuthController.cs]"]
  node_users_api["Users API<br/>[UsersController.cs]"]
  node_geo_api["Geography API"]
  node_lookups_api["Lookups API"]
end

subgraph group_application["Application"]
  node_contact_service["Contact operations<br/>[ContactService.cs]"]
  node_excel_service["Excel transfer"]
  node_account_service["Account operations<br/>[AccountService.cs]"]
  node_registration_service["Registration"]
  node_profile_service["Profile operations<br/>[ProfileService.cs]"]
  node_user_service["User administration"]
  node_geography_service["Geography operations"]
  node_lookup_service["Lookup operations<br/>[LookupService.cs]"]
  node_legacy_service["Legacy import"]
end

subgraph group_infrastructure["Infrastructure"]
  node_contact_repo["Contact repository"]
  node_user_repo["User repository<br/>[UserRepository.cs]"]
  node_lookup_repo["Lookup repository"]
  node_refresh_repo["Refresh tokens"]
  node_verification_repo["Verification codes"]
  node_db[("Application database<br/>[AppDbContext.cs]")]
  node_workbook["Workbook handling<br/>[ContactWorkbook.cs]"]
  node_token_service["Token creation<br/>[TokenService.cs]"]
  node_email_sender["Queued email sender"]
  node_email_queue["Email queue<br/>[EmailQueue.cs]"]
  node_email_dispatcher["Email dispatcher<br/>[EmailDispatcher.cs]"]
end

subgraph group_integrations["Integrations"]
  node_smtp["SMTP service"]
  node_legacy_source["Legacy user source"]
end

node_client(("API client"))

node_client -->|"requests"| node_contacts_api
node_client -->|"requests"| node_account_api
node_client -->|"requests"| node_auth_api
node_client -->|"requests"| node_users_api
node_client -->|"requests"| node_geo_api
node_client -->|"requests"| node_lookups_api
node_contacts_api -->|"delegates"| node_contact_service
node_contacts_api -->|"delegates"| node_excel_service
node_excel_service -->|"reads and writes"| node_contact_repo
node_excel_service -->|"loads lookups"| node_lookup_repo
node_excel_service -->|"reads and writes"| node_workbook
node_account_api -->|"delegates"| node_account_service
node_auth_api -->|"delegates"| node_account_service
node_account_api -->|"delegates"| node_registration_service
node_account_api -->|"delegates"| node_profile_service
node_users_api -->|"delegates"| node_user_service
node_geo_api -->|"delegates"| node_geography_service
node_lookups_api -->|"delegates"| node_lookup_service
node_user_service --> node_user_repo
node_user_repo -->|"queries and updates"| node_db
node_legacy_service --> node_legacy_source
node_email_sender -->|"enqueues"| node_email_queue
node_email_dispatcher -->|"dequeues"| node_email_queue
node_email_dispatcher -->|"sends mail"| node_smtp
node_token_service -.-> node_account_service

click node_contacts_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/ContactsController.cs"
click node_account_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/AccountController.cs"
click node_auth_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/AuthController.cs"
click node_users_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/UsersController.cs"
click node_geo_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/GeographyController.cs"
click node_lookups_api "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/LookupsController.cs"
click node_contact_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ContactService.cs"
click node_excel_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ContactExcelService.cs"
click node_account_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/AccountService.cs"
click node_registration_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/RegistrationService.cs"
click node_profile_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ProfileService.cs"
click node_user_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/UserManagementService.cs"
click node_geography_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/GeographyService.cs"
click node_lookup_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/LookupService.cs"
click node_legacy_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/LegacyUserImportService.cs"
click node_contact_repo "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/ContactRepository.cs"
click node_user_repo "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/UserRepository.cs"
click node_lookup_repo "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/LookupRepository.cs"
click node_refresh_repo "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/RefreshTokenRepository.cs"
click node_verification_repo "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/VerificationCodeRepository.cs"
click node_db "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Persistence/AppDbContext.cs"
click node_workbook "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Excel/ContactWorkbook.cs"
click node_token_service "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Services/TokenService.cs"
click node_email_sender "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/QueuedEmailSender.cs"
click node_email_queue "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/EmailQueue.cs"
click node_email_dispatcher "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/EmailDispatcher.cs"
click node_legacy_source "https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Legacy/LegacyUserSource.cs"

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_contacts_api,node_account_api,node_auth_api,node_users_api,node_geo_api,node_lookups_api,node_client toneBlue
class node_contact_service,node_excel_service,node_account_service,node_registration_service,node_profile_service,node_user_service,node_geography_service,node_lookup_service,node_legacy_service toneAmber
class node_contact_repo,node_user_repo,node_lookup_repo,node_refresh_repo,node_verification_repo,node_db,node_workbook,node_token_service,node_email_sender,node_email_queue,node_email_dispatcher toneMint
class node_smtp,node_legacy_source toneRose
```

## Components

### API

- [Contacts API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/ContactsController.cs): `contact-directory.Api/Controllers/ContactsController.cs`
- [Account API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/AccountController.cs): `contact-directory.Api/Controllers/AccountController.cs`
- [Auth API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/AuthController.cs): `contact-directory.Api/Controllers/AuthController.cs`
- [Users API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/UsersController.cs): `contact-directory.Api/Controllers/UsersController.cs`
- [Geography API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/GeographyController.cs): `contact-directory.Api/Controllers/GeographyController.cs`
- [Lookups API](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Api/Controllers/LookupsController.cs): `contact-directory.Api/Controllers/LookupsController.cs`

### Application

- [Contact operations](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ContactService.cs): `contact-directory.Application/Services/ContactService.cs`
- [Excel transfer](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ContactExcelService.cs): `contact-directory.Application/Services/ContactExcelService.cs`
- [Account operations](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/AccountService.cs): `contact-directory.Application/Services/AccountService.cs`
- [Registration](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/RegistrationService.cs): `contact-directory.Application/Services/RegistrationService.cs`
- [Profile operations](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/ProfileService.cs): `contact-directory.Application/Services/ProfileService.cs`
- [User administration](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/UserManagementService.cs): `contact-directory.Application/Services/UserManagementService.cs`
- [Geography operations](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/GeographyService.cs): `contact-directory.Application/Services/GeographyService.cs`
- [Lookup operations](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/LookupService.cs): `contact-directory.Application/Services/LookupService.cs`
- [Legacy import](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Application/Services/LegacyUserImportService.cs): `contact-directory.Application/Services/LegacyUserImportService.cs`

### Infrastructure

- [Contact repository](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/ContactRepository.cs): `contact-directory.Infrastructure/Repositories/ContactRepository.cs`
- [User repository](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/UserRepository.cs): `contact-directory.Infrastructure/Repositories/UserRepository.cs`
- [Lookup repository](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/LookupRepository.cs): `contact-directory.Infrastructure/Repositories/LookupRepository.cs`
- [Refresh tokens](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/RefreshTokenRepository.cs): `contact-directory.Infrastructure/Repositories/RefreshTokenRepository.cs`
- [Verification codes](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Repositories/VerificationCodeRepository.cs): `contact-directory.Infrastructure/Repositories/VerificationCodeRepository.cs`
- [Application database](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Persistence/AppDbContext.cs): `contact-directory.Infrastructure/Persistence/AppDbContext.cs`
- [Workbook handling](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Excel/ContactWorkbook.cs): `contact-directory.Infrastructure/Excel/ContactWorkbook.cs`
- [Token creation](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Services/TokenService.cs): `contact-directory.Infrastructure/Services/TokenService.cs`
- [Queued email sender](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/QueuedEmailSender.cs): `contact-directory.Infrastructure/Email/QueuedEmailSender.cs`
- [Email queue](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/EmailQueue.cs): `contact-directory.Infrastructure/Email/EmailQueue.cs`
- [Email dispatcher](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Email/EmailDispatcher.cs): `contact-directory.Infrastructure/Email/EmailDispatcher.cs`

### Integrations

- **SMTP service**
- [Legacy user source](https://github.com/strategic-information-department-cidrz/contact-directory-api/blob/main/contact-directory.Infrastructure/Legacy/LegacyUserSource.cs): `contact-directory.Infrastructure/Legacy/LegacyUserSource.cs`

### Other components

- **API client**

## Connections

- API client → Contacts API: requests
- API client → Account API: requests
- API client → Auth API: requests
- API client → Users API: requests
- API client → Geography API: requests
- API client → Lookups API: requests
- Contacts API → Contact operations: delegates
- Contacts API → Excel transfer: delegates
- Excel transfer → Contact repository: reads and writes
- Excel transfer → Lookup repository: loads lookups
- Excel transfer → Workbook handling: reads and writes
- Account API → Account operations: delegates
- Auth API → Account operations: delegates
- Account API → Registration: delegates
- Account API → Profile operations: delegates
- Users API → User administration: delegates
- Geography API → Geography operations: delegates
- Lookups API → Lookup operations: delegates
- User administration → User repository
- User repository → Application database: queries and updates
- Legacy import → Legacy user source
- Queued email sender → Email queue: enqueues
- Email dispatcher → Email queue: dequeues
- Email dispatcher → SMTP service: sends mail
- Token creation → Account operations