# wbern/community-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/wbern/community-assistant
- Repository: https://github.com/wbern/community-assistant

## Overview

##### Project type and purpose
- This is a backend‐only, event-driven microservice built on Akka. It exposes HTTP endpoints to ingest customer emails and drives an agentic workflow using an LLM (OpenAI). Its goal is to collect prospect details for real estate inquiries via a series of AI-driven interactions, persisting the final customer data as events and sending follow-ups when needed.

##### File structure
- Top-level artifacts:
- pom.xml – single Maven module
- docker-compose.yml – local service dependencies (e.g., persistence store)
- CHAT_INTERFACE_ARCHITECTURE.md, ROADMAP.md, CLAUDE files – docs & CLI helpers
- Source packages under src/main/java:
- com.example.Bootstrap – application entrypoint and actor system setup
- community/… – generic sample of chat/email agent (not core for real estate)
- realestate/… – the real estate customer service agent:
– api/EmailEndpoint.java (Akka HTTP route)
– application/ProspectProcessingWorkflow, CustomerServiceAgent, EmailClient, ClientInfoEntity
– domain/ClientState, ClientEvent, ProspectState
- resources/application.conf – config for HTTP port, persistence plugins, OpenAI key

##### README for additional insights
- Main Akka components described:
- HTTP Endpoint (`/emails`)
- Workflow actor (manages state until all info collected)
- Agent (wraps LLM calls and memory; invokes “tools”)
- Event-sourced Entity (persists customer info as a stream of events)
- Timers (schedule/cancel follow-up reminders)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        OpenAI["OpenAI API"]:::external
        SMTP["SMTP/Email Service"]:::external
        PersistenceStore["Persistence Store"]:::persistence
    end

    %% Configuration & Build
    pom["pom.xml"]:::config
    dockerCompose["docker-compose.yml"]:::config
    applicationConf["application.conf"]:::config

    %% Actor System
    subgraph "ActorSystem"
        direction TB
        Bootstrap["Bootstrap"]:::bootstrap

        subgraph "Actors"
            direction TB
            EmailEndpoint["EmailEndpoint (HTTP API)"]:::actor
            Workflow["ProspectProcessingWorkflow Actor"]:::actor
            Agent["CustomerServiceAgent Actor"]:::actor
            ClientEntity["ClientInfoEntity (Event-Sourced Entity)"]:::actor
            Timer["Timer Subsystem"]:::actor
        end

        EmailClient["EmailClient Tool"]:::tool
    end

    %% Relationships
    Bootstrap --> EmailEndpoint
    Bootstrap --> Workflow
    Bootstrap --> Agent
    Bootstrap --> ClientEntity
    Bootstrap --> Timer

    EmailEndpoint -->|"ProcessInquiry"| Workflow
    Workflow -->|"ProcessEmail"| Agent
    Agent -->|"LLMRequest"| OpenAI
    Agent -->|"SendEmailTool.execute()"| EmailClient
    EmailClient -->|"SendEmail"| SMTP
    Agent -->|"SaveInfo"| ClientEntity
    ClientEntity -->|"PersistEvent"| PersistenceStore
    Workflow -->|"ScheduleReminder"| Timer
    Timer -->|"ReminderEvent"| Workflow

    %% Click Events
    click EmailEndpoint "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/api/EmailEndpoint.java"
    click Bootstrap "https://github.com/wbern/community-assistant/blob/main/src/main/java/com/example/Bootstrap.java"
    click Workflow "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/application/ProspectProcessingWorkflow.java"
    click Agent "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/application/CustomerServiceAgent.java"
    click ClientEntity "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/application/ClientInfoEntity.java"
    click EmailClient "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/application/EmailClient.java"
    click ClientEvent "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/domain/ClientEvent.java"
    click ClientState "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/domain/ClientState.java"
    click ProspectState "https://github.com/wbern/community-assistant/blob/main/src/main/java/realestate/domain/ProspectState.java"
    click applicationConf "https://github.com/wbern/community-assistant/blob/main/src/main/resources/application.conf"
    click dockerCompose "https://github.com/wbern/community-assistant/blob/main/docker-compose.yml"
    click pom "https://github.com/wbern/community-assistant/blob/main/pom.xml"

    %% Styles
    classDef actor fill:#D6EFFF,stroke:#0366D6,stroke-width:1px;
    classDef persistence fill:#FFE4B5,stroke:#D2691E,stroke-width:1px;
    classDef external fill:#E2F0D9,stroke:#2E8B57,stroke-width:1px;
    classDef tool fill:#FFF5BA,stroke:#DAA520,stroke-width:1px;
    classDef bootstrap fill:#F0F0F0,stroke:#000000,stroke-width:1px;
    classDef config fill:#F5F5F5,stroke:#888888,stroke-width:1px;
```
