# john-helder/email-automator architecture

> Architecture diagram of the GitHub repository john-helder/email-automator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/john-helder/email-automator
- Repository: https://github.com/john-helder/email-automator

## Overview

Email Automator is a FastAPI-backed email analysis and reply application with a simple web dashboard. Users can register or log in, then submit email text for category-based NLP, structural analysis, or an AI-generated reply; the dashboard is documented to display results. Authentication and the database flow are supported by sampled source. Several analysis modules and frontend scripts were not sampled, so their internal wiring is shown only where supported by source or README capabilities.

Main entry points: [`src/routes/ia_routes.py`](https://github.com/john-helder/email-automator/blob/main/src/routes/ia_routes.py) (Email API routes), [`src/auth/routes/auth_router.py`](https://github.com/john-helder/email-automator/blob/main/src/auth/routes/auth_router.py) (Authentication routes), [`src/auth/service/auth_service.py`](https://github.com/john-helder/email-automator/blob/main/src/auth/service/auth_service.py) (Auth service), [`src/main.py`](https://github.com/john-helder/email-automator/blob/main/src/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_dashboard["Dashboard<br/>[dashboard.html]"]
  node_frontend_auth["Login and registration UI<br/>[auth.js]"]
  node_frontend_ia["Analysis UI<br/>[ia.js]"]
  node_frontend_app["Reply dashboard script<br/>[app.js]"]
end

subgraph group_api["API and routing"]
  node_main["FastAPI application<br/>[main.py]"]
  node_ia_routes["Email API routes<br/>[ia_routes.py]"]
end

subgraph group_auth["Authentication"]
  node_auth_routes["Authentication routes<br/>[auth_router.py]"]
  node_auth_controller["Auth controller<br/>[auth_controller.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_user_model["User model<br/>[user_model.py]"]
  node_security["Password and JWT security"]
end

subgraph group_intelligence["Email intelligence"]
  node_nlp["NLP classification and replies<br/>[nlp_utils.py]"]
  node_email_controller["Email analysis controller"]
  node_email_analyzer["Structural email analyzer<br/>[email_analyzer.py]"]
  node_auto_responder["AI reply service<br/>[auto_responder.py]"]
  node_ia_controller["AI request controller<br/>[ia_controller.py]"]
  node_ia_service["Groq response service<br/>[ia_service.py]"]
end

subgraph group_state["State and AI integration"]
  node_database[("SQLite database<br/>[database.py]")]
  node_groq_config["Groq client setup<br/>[groq_cliente.py]"]
end

node_user(("User"))
node_groq(("Groq API"))

node_user -->|"uses"| node_dashboard
node_user -->|"registers or logs in"| node_frontend_auth
node_dashboard -->|"runs"| node_frontend_app
node_frontend_auth -->|"sends credentials"| node_auth_routes
node_frontend_ia -->|"submits email"| node_ia_routes
node_frontend_app -->|"requests reply"| node_ia_routes
node_main -->|"mounts"| node_auth_routes
node_main -->|"mounts"| node_ia_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"queries and persists"| node_user_model
node_auth_service -->|"uses session"| node_database
node_auth_routes -->|"gets session"| node_database
node_auth_service -->|"hashes and issues token"| node_security
node_auth_routes -->|"validates JWT"| node_security
node_ia_routes -->|"classifies and drafts"| node_nlp
node_ia_routes -->|"dispatches analysis"| node_email_controller
node_email_controller -->|"calls"| node_email_analyzer
node_ia_routes -->|"requests reply"| node_auto_responder
node_ia_routes -->|"dispatches prompt"| node_ia_controller
node_ia_service -->|"gets client"| node_groq_config
node_groq_config -->|"creates client"| node_groq
node_ia_service -->|"sends prompt"| node_groq

click node_dashboard "https://github.com/john-helder/email-automator/blob/main/frontend/dashboard.html"
click node_frontend_auth "https://github.com/john-helder/email-automator/blob/main/frontend/auth.js"
click node_frontend_ia "https://github.com/john-helder/email-automator/blob/main/frontend/ia.js"
click node_frontend_app "https://github.com/john-helder/email-automator/blob/main/frontend/app.js"
click node_main "https://github.com/john-helder/email-automator/blob/main/src/main.py"
click node_auth_routes "https://github.com/john-helder/email-automator/blob/main/src/auth/routes/auth_router.py"
click node_ia_routes "https://github.com/john-helder/email-automator/blob/main/src/routes/ia_routes.py"
click node_auth_controller "https://github.com/john-helder/email-automator/blob/main/src/auth/controller/auth_controller.py"
click node_auth_service "https://github.com/john-helder/email-automator/blob/main/src/auth/service/auth_service.py"
click node_user_model "https://github.com/john-helder/email-automator/blob/main/src/auth/models/user_model.py"
click node_security "https://github.com/john-helder/email-automator/tree/main/src/auth/security"
click node_database "https://github.com/john-helder/email-automator/blob/main/src/database.py"
click node_nlp "https://github.com/john-helder/email-automator/blob/main/src/routes/nlp_utils.py"
click node_email_controller "https://github.com/john-helder/email-automator/blob/main/src/controllers/email_controller.py"
click node_email_analyzer "https://github.com/john-helder/email-automator/blob/main/src/services/email_analyzer.py"
click node_auto_responder "https://github.com/john-helder/email-automator/blob/main/src/services/auto_responder.py"
click node_ia_controller "https://github.com/john-helder/email-automator/blob/main/src/controllers/ia_controller.py"
click node_ia_service "https://github.com/john-helder/email-automator/blob/main/src/services/ia_service.py"
click node_groq_config "https://github.com/john-helder/email-automator/blob/main/src/config/groq_cliente.py"

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_dashboard,node_frontend_auth,node_frontend_ia,node_frontend_app,node_user toneBlue
class node_main,node_ia_routes toneAmber
class node_auth_routes,node_auth_controller,node_auth_service,node_user_model,node_security,node_groq toneMint
class node_nlp,node_email_controller,node_email_analyzer,node_auto_responder,node_ia_controller,node_ia_service toneRose
class node_database,node_groq_config toneIndigo
```

## Components

### Web interface

- [Dashboard](https://github.com/john-helder/email-automator/blob/main/frontend/dashboard.html): `frontend/dashboard.html`
- [Login and registration UI](https://github.com/john-helder/email-automator/blob/main/frontend/auth.js): `frontend/auth.js`
- [Analysis UI](https://github.com/john-helder/email-automator/blob/main/frontend/ia.js): `frontend/ia.js`
- [Reply dashboard script](https://github.com/john-helder/email-automator/blob/main/frontend/app.js): `frontend/app.js`

### API and routing

- [FastAPI application](https://github.com/john-helder/email-automator/blob/main/src/main.py): `src/main.py`
- [Email API routes](https://github.com/john-helder/email-automator/blob/main/src/routes/ia_routes.py): `src/routes/ia_routes.py`

### Authentication

- [Authentication routes](https://github.com/john-helder/email-automator/blob/main/src/auth/routes/auth_router.py): `src/auth/routes/auth_router.py`
- [Auth controller](https://github.com/john-helder/email-automator/blob/main/src/auth/controller/auth_controller.py): `src/auth/controller/auth_controller.py`
- [Auth service](https://github.com/john-helder/email-automator/blob/main/src/auth/service/auth_service.py): `src/auth/service/auth_service.py`
- [User model](https://github.com/john-helder/email-automator/blob/main/src/auth/models/user_model.py): `src/auth/models/user_model.py`
- [Password and JWT security](https://github.com/john-helder/email-automator/tree/main/src/auth/security): `src/auth/security`

### Email intelligence

- [NLP classification and replies](https://github.com/john-helder/email-automator/blob/main/src/routes/nlp_utils.py): `src/routes/nlp_utils.py`
- [Email analysis controller](https://github.com/john-helder/email-automator/blob/main/src/controllers/email_controller.py): `src/controllers/email_controller.py`
- [Structural email analyzer](https://github.com/john-helder/email-automator/blob/main/src/services/email_analyzer.py): `src/services/email_analyzer.py`
- [AI reply service](https://github.com/john-helder/email-automator/blob/main/src/services/auto_responder.py): `src/services/auto_responder.py`
- [AI request controller](https://github.com/john-helder/email-automator/blob/main/src/controllers/ia_controller.py): `src/controllers/ia_controller.py`
- [Groq response service](https://github.com/john-helder/email-automator/blob/main/src/services/ia_service.py): `src/services/ia_service.py`

### State and AI integration

- [SQLite database](https://github.com/john-helder/email-automator/blob/main/src/database.py): `src/database.py`
- [Groq client setup](https://github.com/john-helder/email-automator/blob/main/src/config/groq_cliente.py): `src/config/groq_cliente.py`

### Other components

- **User**
- **Groq API**

## Connections

- User → Dashboard: uses
- User → Login and registration UI: registers or logs in
- Dashboard → Reply dashboard script: runs
- Login and registration UI → Authentication routes: sends credentials
- Analysis UI → Email API routes: submits email
- Reply dashboard script → Email API routes: requests reply
- FastAPI application → Authentication routes: mounts
- FastAPI application → Email API routes: mounts
- Authentication routes → Auth controller: dispatches
- Auth controller → Auth service: calls
- Auth service → User model: queries and persists
- Auth service → SQLite database: uses session
- Authentication routes → SQLite database: gets session
- Auth service → Password and JWT security: hashes and issues token
- Authentication routes → Password and JWT security: validates JWT
- Email API routes → NLP classification and replies: classifies and drafts
- Email API routes → Email analysis controller: dispatches analysis
- Email analysis controller → Structural email analyzer: calls
- Email API routes → AI reply service: requests reply
- Email API routes → AI request controller: dispatches prompt
- Groq response service → Groq client setup: gets client
- Groq client setup → Groq API: creates client
- Groq response service → Groq API: sends prompt