# correspondenceadg-cmyk/luvd1s architecture

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

- Interactive diagram: https://gitdiagram.com/correspondenceadg-cmyk/luvd1s
- Repository: https://github.com/correspondenceadg-cmyk/luvd1s

## Overview

Luvd1s is a multi-tenant personal CRM. Users manage contacts, tags, and interaction history through Vaadin; REST clients can perform related CRUD operations. Service-layer ownership checks scope data to the current user, while writes are audited and instrumented. The dashboard and analytics, contact import, debug console, and optional PII-scrubbed AI chat are additional product capabilities. Some UI, analytics, import, and security wiring is documented but not sampled; those links cite the README rather than implying source inspection.

Main entry points: [`src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java) (Interaction service), [`src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui`](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui) (Vaadin UI), [`src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java) (People service), [`src/main/java/ws/tilda/sentryprotocol/Luvd1s/api`](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/api) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_vaadin["Vaadin UI"]
  node_restapi["REST API"]
end

subgraph group_domain["CRM domain"]
  node_people["People service<br/>[PersonService.java]"]
  node_interactions["Interaction service"]
  node_tags["Tag service<br/>[TagService.java]"]
  node_analytics["CRM analytics"]
  node_importer["Contact import"]
  node_peopledata[("People and tags<br/>[Person.java]")]
  node_interactiondata[("Interaction records<br/>[Interaction.java]")]
  node_userdata[("User records<br/>[User.java]")]
  node_personrepo["People repository"]
  node_interactionrepo["Interaction repository"]
  node_tagrepo["Tag repository<br/>[TagRepository.java]"]
  node_userrepo["User repository"]
end

subgraph group_platform["Security and operations"]
  node_security["Request security"]
  node_userservice["User service<br/>[UserService.java]"]
  node_audit["Audit logging"]
  node_auditdata[("Audit records<br/>[AuditLog.java]")]
  node_auditrepo["Audit repository"]
  node_observability["Metrics and requests"]
  node_debug["Debug console<br/>[DebugService.java]"]
end

subgraph group_assistant["AI assistance"]
  node_chatui["AI chat panel<br/>[AiChatPanel.java]"]
  node_aichat["AI chat orchestration<br/>[AiChatService.java]"]
  node_scrubber["PII scrubber<br/>[PiiScrubber.java]"]
  node_aiservice["AI provider client<br/>[AiService.java]"]
end

node_browser(("Browser user"))
node_restclient(("REST client"))
node_groq["Groq API"]

node_browser -->|"uses"| node_vaadin
node_restclient -->|"calls"| node_restapi
node_vaadin -->|"requests"| node_security
node_restapi -->|"requests"| node_security
node_security -->|"routes"| node_vaadin
node_security -->|"routes"| node_restapi
node_vaadin -->|"uses"| node_people
node_vaadin -->|"uses"| node_interactions
node_vaadin -->|"shows"| node_analytics
node_vaadin -.->|"imports contacts"| node_importer
node_restapi -->|"delegates to"| node_people
node_restapi -->|"delegates to"| node_interactions
node_restapi -->|"delegates to"| node_tags
node_people -->|"queries and saves"| node_personrepo
node_people -->|"gets current user"| node_userservice
node_interactions -->|"queries and saves"| node_interactionrepo
node_interactions -->|"refreshes contact date"| node_personrepo
node_interactions -->|"gets current user"| node_userservice
node_people -->|"records writes"| node_audit
node_interactions -->|"records writes"| node_audit
node_people -->|"records events"| node_observability
node_interactions -->|"records events"| node_observability
node_audit -->|"persists entries"| node_auditrepo
node_audit -->|"counts writes"| node_observability
node_debug -->|"reads metrics"| node_observability
node_chatui -.->|"sends prompts"| node_aichat
node_aichat -->|"gets contacts"| node_people
node_aichat -->|"gets activity"| node_interactions
node_aichat -->|"scrubs context"| node_scrubber
node_aichat -->|"sends messages"| node_aiservice
node_aiservice -->|"calls provider"| node_groq

click node_vaadin "https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui"
click node_restapi "https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/api"
click node_security "https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/security"
click node_people "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java"
click node_interactions "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java"
click node_tags "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/TagService.java"
click node_analytics "https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service"
click node_importer "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ContactImporter.java"
click node_peopledata "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Person.java"
click node_interactiondata "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Interaction.java"
click node_userdata "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/User.java"
click node_personrepo "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/PersonRepository.java"
click node_interactionrepo "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/InteractionRepository.java"
click node_tagrepo "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/TagRepository.java"
click node_userrepo "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/UserRepository.java"
click node_userservice "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/UserService.java"
click node_audit "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AuditLogService.java"
click node_auditdata "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/AuditLog.java"
click node_auditrepo "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/AuditLogRepository.java"
click node_observability "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ObservabilityService.java"
click node_debug "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/DebugService.java"
click node_chatui "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui/components/AiChatPanel.java"
click node_aichat "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java"
click node_scrubber "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PiiScrubber.java"
click node_aiservice "https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiService.java"

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_vaadin,node_restapi,node_browser,node_restclient toneBlue
class node_people,node_interactions,node_tags,node_analytics,node_importer,node_peopledata,node_interactiondata,node_userdata,node_personrepo,node_interactionrepo,node_tagrepo,node_userrepo toneAmber
class node_security,node_userservice,node_audit,node_auditdata,node_auditrepo,node_observability,node_debug,node_groq toneMint
class node_chatui,node_aichat,node_scrubber,node_aiservice toneRose
```

## Components

### User interfaces

- [Vaadin UI](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui`
- [REST API](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/api): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/api`

### CRM domain

- [People service](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`
- [Interaction service](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`
- [Tag service](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/TagService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/TagService.java`
- [CRM analytics](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service`
- [Contact import](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ContactImporter.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ContactImporter.java`
- [People and tags](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Person.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Person.java`
- [Interaction records](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Interaction.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/Interaction.java`
- [User records](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/User.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/User.java`
- [People repository](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/PersonRepository.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/PersonRepository.java`
- [Interaction repository](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/InteractionRepository.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/InteractionRepository.java`
- [Tag repository](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/TagRepository.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/TagRepository.java`
- [User repository](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/UserRepository.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/UserRepository.java`

### Security and operations

- [Request security](https://github.com/correspondenceadg-cmyk/luvd1s/tree/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/security): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/security`
- [User service](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/UserService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/UserService.java`
- [Audit logging](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AuditLogService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AuditLogService.java`
- [Audit records](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/AuditLog.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/data/AuditLog.java`
- [Audit repository](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/AuditLogRepository.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/repository/AuditLogRepository.java`
- [Metrics and requests](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ObservabilityService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/ObservabilityService.java`
- [Debug console](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/DebugService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/DebugService.java`

### AI assistance

- [AI chat panel](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui/components/AiChatPanel.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui/components/AiChatPanel.java`
- [AI chat orchestration](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java`
- [PII scrubber](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PiiScrubber.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PiiScrubber.java`
- [AI provider client](https://github.com/correspondenceadg-cmyk/luvd1s/blob/main/src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiService.java): `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiService.java`

### Other components

- **Browser user**
- **REST client**
- **Groq API**

## Connections

- Browser user → Vaadin UI: uses
- REST client → REST API: calls
- Vaadin UI → Request security: requests
- REST API → Request security: requests
- Request security → Vaadin UI: routes
- Request security → REST API: routes
- Vaadin UI → People service: uses
- Vaadin UI → Interaction service: uses
- Vaadin UI → CRM analytics: shows (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui/components/AiChatPanel.java`)
- Vaadin UI → Contact import: imports contacts
- REST API → People service: delegates to (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/api/PersonApiController.java`)
- REST API → Interaction service: delegates to (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/api/InteractionApiController.java`)
- REST API → Tag service: delegates to (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/api/TagApiController.java`)
- People service → People repository: queries and saves (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`)
- People service → User service: gets current user (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`)
- Interaction service → Interaction repository: queries and saves (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`)
- Interaction service → People repository: refreshes contact date (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`)
- Interaction service → User service: gets current user (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`)
- People service → Audit logging: records writes (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`)
- Interaction service → Audit logging: records writes (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`)
- People service → Metrics and requests: records events (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/PersonService.java`)
- Interaction service → Metrics and requests: records events (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/InteractionService.java`)
- Audit logging → Audit repository: persists entries (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AuditLogService.java`)
- Audit logging → Metrics and requests: counts writes (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AuditLogService.java`)
- Debug console → Metrics and requests: reads metrics (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/DebugService.java`)
- AI chat panel → AI chat orchestration: sends prompts (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/ui/components/AiChatPanel.java`)
- AI chat orchestration → People service: gets contacts (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java`)
- AI chat orchestration → Interaction service: gets activity (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java`)
- AI chat orchestration → PII scrubber: scrubs context (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java`)
- AI chat orchestration → AI provider client: sends messages (evidence: `src/main/java/ws/tilda/sentryprotocol/Luvd1s/service/AiChatService.java`)
- AI provider client → Groq API: calls provider
