# deryayildirimm/smartlead-ai architecture

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

- Interactive diagram: https://gitdiagram.com/deryayildirimm/smartlead-ai
- Repository: https://github.com/deryayildirimm/smartlead-ai
- Video tour (about a minute): https://gitdiagram.com/deryayildirimm/smartlead-ai/video

## Overview

This is a Flask reading-assistant application: users can chat about short readings, while prospective users submit interest leads and administrators list them. The main paths are request validation → assistant/provider response, and lead validation → SQLite persistence → lead listing. The graph reflects the sampled runtime source; the README is empty, so frontend behavior beyond the named templates is not assumed.

Main entry points: [`app/routes.py`](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py) (Lead endpoints), [`app/services/ai_service.py`](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/services/ai_service.py) (AI service), [`app/__init__.py`](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/__init__.py) (App factory), [`app/database.py`](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/database.py) (Lead data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app_factory["App factory<br/>[__init__.py]"]
  node_page_routes["Page routes<br/>[routes.py]"]
  node_home_page["Home page<br/>[index.html]"]
  node_dashboard["Dashboard<br/>[dashboard.html]"]
  node_health["Health endpoint<br/>[__init__.py]"]
end

subgraph group_assistant["Reading assistant"]
  node_chat_route["Chat endpoint<br/>[routes.py]"]
  node_chat_validation["Chat validation<br/>[validators.py]"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_assistant_prompt["Assistant prompt"]
end

subgraph group_leads["Lead management"]
  node_lead_route["Lead endpoints<br/>[routes.py]"]
  node_lead_validation["Lead validation<br/>[validators.py]"]
  node_lead_store["Lead data access<br/>[database.py]"]
  node_sqlite[("SQLite database<br/>[database.py]")]
end

subgraph group_platform["Configuration and errors"]
  node_configuration["Runtime configuration<br/>[config.py]"]
  node_error_handlers["Error handlers<br/>[errors.py]"]
end

node_visitor(("Visitor"))
node_admin(("Administrator"))
node_groq{{"Groq API"}}

node_visitor -->|"requests pages"| node_page_routes
node_page_routes -->|"renders"| node_home_page
node_page_routes -->|"renders"| node_dashboard
node_visitor -->|"sends chat"| node_chat_route
node_chat_route -->|"validates via"| node_chat_validation
node_chat_route -->|"requests reply"| node_ai_service
node_ai_service -->|"validates chat"| node_chat_validation
node_ai_service -->|"sends completion"| node_groq
node_groq -->|"returns completion"| node_ai_service
node_configuration -->|"loads prompt"| node_assistant_prompt
node_admin -->|"lists leads"| node_lead_route
node_visitor -->|"submits lead"| node_lead_route
node_lead_route -->|"validates via"| node_lead_validation
node_lead_route -->|"creates or lists"| node_lead_store
node_lead_store -->|"reads and writes"| node_sqlite
node_app_factory -->|"loads settings"| node_configuration
node_app_factory -->|"registers service"| node_ai_service
node_app_factory -->|"initializes database"| node_lead_store
node_app_factory -->|"registers handlers"| node_error_handlers
node_visitor -->|"checks status"| node_health
node_chat_route -->|"errors handled by"| node_error_handlers
node_lead_route -->|"errors handled by"| node_error_handlers

click node_app_factory "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/__init__.py"
click node_page_routes "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py"
click node_home_page "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/templates/index.html"
click node_dashboard "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/templates/dashboard.html"
click node_health "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/__init__.py"
click node_chat_route "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py"
click node_chat_validation "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/validators.py"
click node_ai_service "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/services/ai_service.py"
click node_assistant_prompt "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/prompts/reading_assistant.txt"
click node_lead_route "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py"
click node_lead_validation "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/validators.py"
click node_lead_store "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/database.py"
click node_sqlite "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/database.py"
click node_configuration "https://github.com/deryayildirimm/smartlead-ai/blob/main/config.py"
click node_error_handlers "https://github.com/deryayildirimm/smartlead-ai/blob/main/app/errors.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_app_factory,node_page_routes,node_home_page,node_dashboard,node_health toneBlue
class node_chat_route,node_chat_validation,node_ai_service,node_assistant_prompt toneAmber
class node_lead_route,node_lead_validation,node_lead_store,node_sqlite,node_groq toneMint
class node_configuration,node_error_handlers toneRose
class node_visitor,node_admin toneIndigo
```

## Components

### Web application

- [App factory](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/__init__.py): `app/__init__.py`
- [Page routes](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py): `app/routes.py`
- [Home page](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/templates/index.html): `app/templates/index.html`
- [Dashboard](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/templates/dashboard.html): `app/templates/dashboard.html`
- [Health endpoint](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/__init__.py): `app/__init__.py`

### Reading assistant

- [Chat endpoint](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py): `app/routes.py`
- [Chat validation](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/validators.py): `app/validators.py`
- [AI service](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/services/ai_service.py): `app/services/ai_service.py`
- [Assistant prompt](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/prompts/reading_assistant.txt): `app/prompts/reading_assistant.txt`

### Lead management

- [Lead endpoints](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/routes.py): `app/routes.py`
- [Lead validation](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/validators.py): `app/validators.py`
- [Lead data access](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/database.py): `app/database.py`
- [SQLite database](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/database.py): `app/database.py`

### Configuration and errors

- [Runtime configuration](https://github.com/deryayildirimm/smartlead-ai/blob/main/config.py): `config.py`
- [Error handlers](https://github.com/deryayildirimm/smartlead-ai/blob/main/app/errors.py): `app/errors.py`

### Other components

- **Visitor**
- **Administrator**
- **Groq API**

## Connections

- Visitor → Page routes: requests pages
- Page routes → Home page: renders
- Page routes → Dashboard: renders
- Visitor → Chat endpoint: sends chat
- Chat endpoint → Chat validation: validates via
- Chat endpoint → AI service: requests reply
- AI service → Chat validation: validates chat
- AI service → Groq API: sends completion
- Groq API → AI service: returns completion
- Runtime configuration → Assistant prompt: loads prompt
- Administrator → Lead endpoints: lists leads
- Visitor → Lead endpoints: submits lead
- Lead endpoints → Lead validation: validates via
- Lead endpoints → Lead data access: creates or lists
- Lead data access → SQLite database: reads and writes
- App factory → Runtime configuration: loads settings
- App factory → AI service: registers service
- App factory → Lead data access: initializes database
- App factory → Error handlers: registers handlers
- Visitor → Health endpoint: checks status
- Chat endpoint → Error handlers: errors handled by
- Lead endpoints → Error handlers: errors handled by