Schedule and Sales Management Platform

Welcome to the Clientello project repository! This is an innovative platform that combines the management of schedules and product sales with automated customer service through artificial intelligence. Through an integrated approach, Clientello offers a complete solution to optimize and automate scheduling and sales processes, enhancing the experience for both customers and business managers.

This will open a window for authentication and scanning the WhatsApp QR Code.

---

Architecture

Overview

Clientello is a multi-platform scheduling and sales management platform with integrated AI-powered customer service through WhatsApp. The system follows a Clean Architecture approach with clear separation of concerns across multiple layers and components.

High-Level Architecture:

• Backend: .NET 6 Web API with layered architecture (Core.Domain, Domain, Application, Infra, API)
• Clients:
  • Portal: Angular 17 web application for business management
  • Messenger: Electron desktop application for WhatsApp integration
  • Mobile: Flutter application (experimental/in development)
• Infrastructure: MongoDB (data), Redis (caching), Docker (containerization)
• Integrations: OpenAI API, AWS SNS, External APIs (ZIP code, currency)

Components & Responsibilities

Component	Technology	Responsibility	Evidence
API	.NET 6 Web API	REST API endpoints, authentication (JWT), Swagger documentation, middleware	server/src/API
Application	.NET 6 Class Library	Business logic orchestration, service layer, DTOs/ViewModels, AutoMapper configurations	server/src/Application
Domain	.NET 6 Class Library	Business entities, domain validations (FluentValidation), domain-specific logic	server/src/Domain
Core.Domain	.NET 6 Class Library	Core abstractions, base entities, interfaces, events, MediatR handlers, value objects	server/src/Core.Domain
Infra	.NET 6 Class Library	Data access (MongoDB repositories), external service integrations, caching (Redis)	server/src/Infra
Portal	Angular 17	Web client for business managers (schedules, sales, configuration, analytics)	client/portal
Messenger	Electron + Node.js	WhatsApp bot using whatsapp-web.js for AI-powered automated customer service	client/messenger
Mobile	Flutter	Mobile application (experimental/early stage)	client/mobile

Folder Structure

Backend (Server)

server/
├── src/
│   ├── API/                          # Presentation Layer
│   │   ├── Controllers/              # REST API controllers
│   │   ├── Configurations/           # DI, Auth, CORS, AutoMapper setup
│   │   ├── Middlewares/              # Custom middleware (ActiveStatusCheck)
│   │   ├── Models/                   # API-specific models
│   │   ├── Resources/                # Templates for AI prompts and notifications
│   │   └── Program.cs                # Application entry point
│   │
│   ├── Application/                  # Application Layer
│   │   ├── Services/                 # Service implementations (business orchestration)
│   │   ├── Interfaces/               # Service contracts
│   │   ├── ViewModels/               # DTOs for API communication
│   │   ├── Mapping/                  # AutoMapper profiles
│   │   └── ApplicationService.cs     # Base service with notification handling
│   │
│   ├── Domain/                       # Domain Layer (business-specific)
│   │   ├── Activities/               # Activity aggregate (entity, repository, validations)
│   │   ├── Categories/               # Category aggregate
│   │   ├── Companies/                # Company aggregate
│   │   ├── Customers/                # Customer aggregate
│   │   ├── Employees/                # Employee aggregate
│   │   ├── Schedules/                # Schedule aggregate
│   │   └── [other aggregates]/       # Each with Entity, Repository interface, Validations
│   │
│   ├── Core.Domain/                  # Core Domain Layer (shared)
│   │   ├── Entities/                 # Base Entity class
│   │   ├── Events/                   # Domain events (Event, Message)
│   │   ├── Interfaces/               # Core interfaces (IRepository, IMediatorHandler, etc.)
│   │   ├── Notifications/            # DomainNotification, MediatorHandler
│   │   ├── Validations/              # Base validators (DomainValidator)
│   │   └── ValueObjects/             # Shared value objects
│   │
│   └── Infra/                        # Infrastructure Layer
│       ├── Data/                     # MongoDB repository implementations
│       ├── Services/                 # External service integrations (OpenAI, AWS SNS, Redis)
│       └── CrossCutting/             # DI bootstrapper
│
├── environments/                     # Environment-specific configuration files
├── docker-compose.yml                # Local development infrastructure
├── docker-compose.production.yml     # Production infrastructure
├── Dockerfile                        # .NET API Docker image
└── Clientello.sln                    # Visual Studio solution

Dependency Direction: API → Application → Domain ← Infra
(Infra depends on Domain for interfaces; Domain has no dependencies on outer layers)

Frontend

client/
├── portal/                           # Angular Web Application
│   └── src/
│       ├── app/
│       │   ├── authentication/       # Login, auth guards
│       │   ├── management/           # Business management pages
│       │   ├── services/             # HTTP services for API communication
│       │   ├── models/               # TypeScript models
│       │   └── shared/               # Shared components
│       └── environments/             # Environment configurations
│
├── messenger/                        # Electron Desktop App
│   ├── main.js                       # Electron main process
│   ├── window.js                     # Window management
│   ├── qrcode.js                     # QR code handling
│   ├── repository.js                 # API communication
│   ├── caching.js                    # Local caching
│   ├── antispam.js                   # Message throttling
│   ├── token.js                      # JWT token management
│   └── pages/                        # Electron renderer pages (HTML)
│
└── mobile/                           # Flutter Mobile App (experimental)
    └── lib/
        └── main.dart                 # Flutter entry point

Key Patterns

Pattern	Where Used	Evidence	Description
Repository	Data access layer	Infra/Data, Core.Domain/Interfaces/IRepository.cs	Generic repository pattern for MongoDB with MongoRepository<T> base class and entity-specific implementations
Dependency Injection	Throughout backend	API/Configurations/DependencyInjectionConfiguration.cs, Infra/CrossCutting/Bootstrapper.cs	Constructor injection for all dependencies, configured in Program.cs and bootstrapper
Domain Notification	Error handling	Core.Domain/Notifications, API/Controllers/BaseController.cs	Collects and propagates domain validation errors via MediatR notifications instead of exceptions
Mediator (MediatR)	Event handling	Core.Domain/Notifications/MediatorHandler.cs	Mediator pattern for publishing domain events and notifications
Specification	Domain validation	Domain/*/Specifications, Core.Domain/Validations	FluentValidation-based specifications for entity validation with DomainValidator<T>
Options Pattern	Configuration	API/appsettings.json	Structured configuration via appsettings.json (MongoDB, Redis, JWT, SMTP, AWS, OpenAI)
DTO/ViewModel	Data transfer	Application/ViewModels	Separation between domain entities and API contracts
AutoMapper	Object mapping	Application/Mapping, API/Configurations/AutoMapperConfiguration.cs	Automated mapping between entities and ViewModels
Middleware Pipeline	Request processing	API/Middlewares/ActiveStatusCheckMiddleware.cs	Custom middleware for checking company/employee active status on authenticated requests
Template Method	AI prompt generation	API/Resources	Handlebars templates for AI prompts and notification messages
Factory	Service instantiation	Infra/CrossCutting/Bootstrapper.cs	Service factory pattern via DI container (Singleton, Scoped lifetimes)
Strategy	AI model selection	Application/Services/AnsweringService.cs	Different OpenAI models (GPT-3.5, GPT-4) selected based on context

Runtime / Deployment

Local Development

Prerequisites:

• Docker Desktop
• .NET 6 SDK
• Node.js 18+
• Angular CLI

Infrastructure (MongoDB + Redis):

cd server
docker-compose up -d

See: server/docker-compose.yml

Backend API:

cd server/src/API
dotnet restore
dotnet run

API runs on http://localhost:43595 with Swagger UI at /swagger

Portal (Web Client):

cd client/portal
npm install
ng serve

Portal runs on http://localhost:4200

Messenger (Desktop Client):

cd client/messenger
npm install
npm start

Production Deployment

CI/CD Pipeline:

• GitHub Actions workflows for automated deployment
• Production: .github/workflows/production_environment.yml
• Development: .github/workflows/development_environment.yml

Deployment Strategy:

Component	Deployment Method	Evidence
API	Docker container on self-hosted Linux server	server/Dockerfile, server/production.sh
Portal	AWS S3 + CloudFront (CDN)	production_environment.yml lines 32-47
Messenger	GitHub Releases (Windows executable)	client/messenger/package.json, messenger_build.yml

Infrastructure Stack:

# Production containers (see: server/docker-compose.production.yml)
services:
  api:        # .NET 6 Web API
  mongo:      # MongoDB database
  redis:      # Redis cache

Environment Configuration:

• Local: server/environments/local.env
• Development: server/environments/dev.env
• Production: server/environments/prod.env

Key Configuration Sections (see: server/src/API/appsettings.json):

• mongoConnection: Database connection string
• JwtToken: Authentication configuration
• redis: Caching endpoint and credentials
• openAi: API key and endpoint for AI features
• smtp: Email notification settings
• aws.sns: SMS notification via AWS SNS

Data Flow

Main User Flows

1. Schedule Management Flow (Portal → API → Database)

[Angular Portal] 
    ↓ HTTP POST /schedules
[API/SchedulesController] 
    ↓ Validates JWT token
[ActiveStatusCheckMiddleware] 
    ↓ Checks company/employee status
[ScheduleService] 
    ↓ Business logic + validation
[ScheduleRepository] 
    ↓ MongoDB query
[MongoDB Collection: Schedule]

2. WhatsApp AI-Powered Customer Service Flow

[WhatsApp Message] 
    ↓ whatsapp-web.js webhook
[Messenger/main.js] 
    ↓ HTTP POST /answering
[API/AnsweringController] 
    ↓ Authentication
[AnsweringService] 
    ↓ AI prompt preparation with Handlebars templates
[OpenAIService] 
    ↓ HTTP POST to OpenAI API
[GPT Model Response] 
    ↓ Parse action/intent
[AnsweringService] 
    ↓ Execute action (schedule, pricing, question)
[Messenger/main.js] 
    ↓ Send response via WhatsApp
[Customer]

3. Authentication Flow

[Client] 
    ↓ POST /users/authenticate {email, password}
[API/UsersController] 
    ↓ Validate credentials
[UserService] 
    ↓ Password verification (encryption)
[UserRepository] 
    ↓ Query MongoDB
[JWT Token Generation] 
    ↓ Return token
[Client stores token] 
    ↓ Subsequent requests include Authorization header
[API validates JWT]

Data Flow Diagram

flowchart TB
    subgraph Clients
        Portal[Angular Portal<br/>Web Management]
        Messenger[Electron Messenger<br/>WhatsApp Bot]
        Mobile[Flutter Mobile<br/>experimental]
    end

    subgraph API_Layer["API Layer (ASP.NET Core)"]
        Controllers[Controllers]
        Middleware[Middlewares<br/>Auth, ActiveStatus]
        Auth[JWT Authentication]
    end

    subgraph Application_Layer["Application Layer"]
        Services[Services<br/>Business Orchestration]
        ViewModels[ViewModels/DTOs]
        Mapper[AutoMapper]
    end

    subgraph Domain_Layer["Domain Layer"]
        Entities[Domain Entities]
        Validations[FluentValidation<br/>Specifications]
        DomainEvents[Domain Events<br/>MediatR]
    end

    subgraph Infrastructure_Layer["Infrastructure Layer"]
        Repositories[MongoDB Repositories]
        ExternalServices[External Services<br/>OpenAI, AWS SNS, APIs]
        Cache[Redis Caching]
    end

    subgraph External_Systems["External Systems"]
        MongoDB[(MongoDB<br/>Document Store)]
        Redis[(Redis<br/>Cache)]
        OpenAI[OpenAI API<br/>GPT-3.5/GPT-4]
        AWS[AWS SNS<br/>SMS Notifications]
        WhatsApp[WhatsApp<br/>Web API]
        Email[SMTP<br/>Email Service]
    end

    Portal -->|HTTP/REST| Controllers
    Messenger -->|HTTP/REST| Controllers
    Mobile -->|HTTP/REST| Controllers
    
    Controllers --> Middleware
    Middleware --> Auth
    Auth --> Services
    
    Services --> ViewModels
    Services --> Mapper
    Services --> Entities
    Services --> DomainEvents
    
    Entities --> Validations
    
    Services --> Repositories
    Services --> ExternalServices
    Services --> Cache
    
    Repositories --> MongoDB
    Cache --> Redis
    ExternalServices --> OpenAI
    ExternalServices --> AWS
    ExternalServices --> Email
    
    Messenger <--> WhatsApp
    
    style API_Layer fill:#e1f5ff
    style Application_Layer fill:#fff4e6
    style Domain_Layer fill:#f3e5f5
    style Infrastructure_Layer fill:#e8f5e9

Loading

Integration Patterns

Database (MongoDB):

• ORM/Driver: MongoDB.Driver (official C# driver)
• Connection: Connection string in appsettings.json
• Pattern: Repository pattern with MongoRepository<T> base class
• Collections: One per domain aggregate (Company, Employee, Customer, Schedule, etc.)
• Evidence: Infra/Data/MongoRepository.cs

Caching (Redis):

• Library: StackExchange.Redis
• Usage: Caching API responses, temporary data for AI conversations
• Configuration: Endpoint, password, SSL in appsettings
• Evidence: Infra/Services/RedisCachingService.cs

Authentication & Authorization:

• Mechanism: JWT Bearer tokens
• Claims: UserId, Role (Company, Employee, Admin), AssociatedId
• Middleware: Custom ActiveStatusCheckMiddleware validates company/employee status
• Evidence: API/Configurations/AuthenticationConfiguration.cs, API/Middlewares/ActiveStatusCheckMiddleware.cs

AI Integration (OpenAI):

• Models: GPT-3.5-turbo-16k, GPT-4
• Usage: Intent recognition, automated responses, scheduling via natural language
• Templates: Handlebars templates in API/Resources for prompt engineering
• Evidence: Infra/Services/OpenAIService.cs, Application/Services/AnsweringService.cs

Messaging (WhatsApp):

• Library: whatsapp-web.js (Node.js)
• Client: Electron desktop application
• Authentication: QR code scan (LocalAuth strategy)
• Evidence: client/messenger/main.js

Notifications:

• Email: SMTP configuration in appsettings
• SMS: AWS SNS integration
• Templates: Handlebars templates in API/Resources/notifications
• Evidence: Infra/Services/NotificationService.cs

External APIs:

• ZIP Code Lookup: pagar.me API (Brazilian addresses)
• Currency Conversion: awesomeapi.com.br
• Evidence: Infra/Services/ZipCodeService.cs, Infra/Services/CurrencyService.cs

Observability

Logging:

• Framework: ASP.NET Core built-in logging (ILogger)
• Configuration: appsettings.json Logging section
• Evidence: API/appsettings.json lines 3-8

Environment Tracking:

• Current environment logged on startup via IConfiguration["CurrentEnvironment"]
• Evidence: API/Program.cs line 72

Error Handling:

• Domain validation errors collected via DomainNotification pattern
• HTTP responses include structured error messages via ErrorResponse model
• Evidence: API/Controllers/BaseController.cs

API Documentation:

• Swagger/OpenAPI automatically generated for all endpoints
• Available at /swagger in non-production environments
• Evidence: API/Program.cs lines 13-35

Note: Advanced observability (distributed tracing, metrics, centralized logging) is not currently implemented. Indicated areas for future enhancement include Application Insights, Serilog, or OpenTelemetry integration.

Best Practices Identified

1. Clean Architecture: Strict layer separation with dependency inversion (Domain is independent, Infra implements interfaces)
2. Domain-Driven Design: Aggregates organized by business concepts (Company, Schedule, Customer)
3. Validation at Domain Level: FluentValidation specifications ensure business rules are enforced before persistence
4. Fail-Fast with Notifications: Domain notifications collect all errors instead of throwing exceptions early
5. Immutable Configuration: Options pattern with strongly-typed configuration objects
6. Separation of Concerns: DTOs/ViewModels separate API contracts from domain entities
7. Repository Abstraction: Data access logic isolated from business logic
8. Dependency Injection: Loose coupling via constructor injection throughout
9. Multi-Platform Strategy: Single backend serves web, desktop, and mobile clients
10. AI-First Customer Service: Natural language processing for scheduling and support automation

Technology Stack Summary

Backend:

• Runtime: .NET 6
• Web Framework: ASP.NET Core Web API
• Database: MongoDB (document-based)
• Cache: Redis
• Validation: FluentValidation
• Object Mapping: AutoMapper
• Mediator: MediatR
• Authentication: JWT Bearer tokens
• AI: OpenAI API (GPT-3.5/GPT-4)

Frontend:

• Web Portal: Angular 17, Angular Material, Bootstrap 5
• Desktop Bot: Electron, Node.js, whatsapp-web.js
• Mobile: Flutter (experimental)

Infrastructure:

• Containerization: Docker, Docker Compose
• CI/CD: GitHub Actions
• Cloud: AWS (S3, CloudFront, SNS)
• Version Control: Git, GitHub