# tamerhabbass/sms_lead_api architecture

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

- Interactive diagram: https://gitdiagram.com/tamerhabbass/sms_lead_api
- Repository: https://github.com/tamerhabbass/sms_lead_api

## Overview

1. **Overall shape**
   - This is a **Python/Django** project named `SMS_Lead_API`.
   - The repository is organized into one Django project package, `api`, plus three feature apps: `authentication`, `reporting`, and `sms_lead`.

2. **Runtime and deployment boundary**
   - `api/asgi.py`, `api/wsgi.py`, and `manage.py` show the standard Django runtime split:
     - HTTP/API serving through Django
     - ASGI support for async/server deployment
     - management-command execution for batch and scheduler jobs
   - `api/settings.py` and `api/urls.py` are the central composition points for wiring the apps together.

3. **Authentication subsystem**
   - The `authentication` app owns identity-related concerns: models, serializers, views, URLs, and a custom renderer/util layer.
   - Its structure suggests a **custom auth/API contract** rather than a thin default Django auth setup.
   - `authentication/migrations/0001_initial.py` indicates this app maintains its own persisted auth schema.

4. **Lead/SMS domain subsystem**
   - `sms_lead` is the main business-domain app.
   - It contains its own models, views, URLs, admin registration, tests, and multiple migrations, which implies it is the primary data-bearing subsystem.
   - The presence of `sms_run.py` strongly suggests this app encapsulates the SMS dispatch or message-processing logic separate from request handlers.

5. **Scheduler and background processing**
   - `sms_lead/management/commands/createscheduler.py`, `runapscheduler.py`, `runreporting.py`, and `jobstores.py` indicate **background jobs are first-class** in this repo.
   - The architecture includes scheduled execution via APScheduler-style command entrypoints rather than relying only on web requests.
   - This is a key boundary: interactive API/UI code lives in views, while recurring work is executed through management commands.

6. **Reporting subsystem**
   - The `reporting` app is responsible for report generation and presentation.
   - `generate_report.py`, `forms.py`, `util.py`, and `views.py` indicate a pipeline that likely collects domain data, applies filters/ranges, and produces outputs.
   - The app also contains HTML templates for report pages and email content, so reporting spans both UI and notification output.

7. **Presentation layer**
   - Reporting is the only app with templates checked in, including `main.html`, `reporting.html`, `reportingCustomRange.html`, and email subject templates.
   - This means the repo is not purely API-only; it mixes **server-rendered reporting views** with API-style app structure.
   - The API/front-controller boundary is still Django URL routing, but the reporting module renders HTML responses and likely email content as well.

8. **Data model and persistence**
   - Each app has its own migrations, so the schema is split by responsibility rather than centralized.
   - Django ORM is the persistence layer across the project.
   - `authentication/admin.py`, `reporting/admin.py`, and `sms_lead/admin.py` show that the data can also be managed through the Django admin interface.

9. **Cross-app interaction**
   - The likely flow is:
     - authenticated users access reporting or SMS-lead endpoints,
     - domain data is stored through the `sms_lead` models,
     - reporting logic reads that data and produces exports or rendered reports,
     - scheduler commands trigger recurring report/SMS jobs.
   - `authentication` sits as a supporting boundary used by the other app views rather than being the core business domain itself.

10. **Artifacts and outputs**
   - The root-level `Rental_Forgiveness_*.csv` files look like generated report/export artifacts or sample data outputs, not source code.
   - Their presence suggests the system produces CSV-based reporting or batch outputs as part of its workflow.

11. **What to draw in an architecture diagram**
   - Draw one Django project container with three internal app boundaries:
     - **Authentication**
     - **SMS Lead / lead-processing**
     - **Reporting**
   - Add a separate **background jobs/scheduler** lane connected to `sms_lead`.
   - Show **Django ORM + migrations** as the persistence layer underneath all apps.
   - Show **templates/email output** attached to reporting, and optionally CSV export artifacts as output from reporting jobs.

Main entry points: [`api/settings.py`](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/settings.py) (Settings), [`sms_lead/__init__.py`](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/__init__.py) (SMS Lead App), [`reporting/__init__.py`](https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/__init__.py) (Reporting App), [`api/urls.py`](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/urls.py) (Root URLs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_manage_py["manage.py<br/>management entrypoint<br/>[manage.py]"]
  node_settings["Settings<br/>django config<br/>[settings.py]"]
  node_root_urls["Root URLs<br/>router<br/>[urls.py]"]
  node_asgi["ASGI<br/>async server entrypoint<br/>[asgi.py]"]
  node_wsgi["WSGI<br/>server entrypoint<br/>[wsgi.py]"]
end

subgraph group_auth["Authentication"]
  node_auth_app{{"Auth App<br/>identity app<br/>[__init__.py]"}}
  node_auth_api["Auth API<br/>serializers/views<br/>[serializers.py]"]
end

subgraph group_domain["SMS Lead"]
  node_sms_app{{"SMS Lead App<br/>domain app<br/>[__init__.py]"}}
  node_sms_domain[("Lead Models<br/>orm models<br/>[models.py]")]
  node_sms_api["Lead Views<br/>request handlers<br/>[views.py]"]
  node_sms_runner["SMS Runner<br/>dispatch logic<br/>[sms_run.py]"]
end

subgraph group_reporting["Reporting"]
  node_report_app{{"Reporting App<br/>[__init__.py]"}}
  node_report_pipeline["Report Pipeline<br/>generation pipeline<br/>[generate_report.py]"]
  node_report_views["Report Views<br/>views/forms<br/>[views.py]"]
end

subgraph group_jobs["Background Jobs"]
  node_job_commands["Job Commands<br/>scheduler commands<br/>[runapscheduler.py]"]
  node_scheduler_store["Job Stores<br/>scheduler config<br/>[jobstores.py]"]
end

subgraph group_data["Persistence"]
  node_orm_layer[("ORM + Migrations<br/>persistence layer<br/>[0001_initial.py]")]
end

subgraph group_outputs["Outputs"]
  node_report_templates["Report Templates<br/>html/email templates<br/>[reporting.html]"]
  node_csv_exports["CSV Exports<br/>report artifacts"]
end

node_manage_py -->|"loads"| node_settings
node_settings -->|"wires"| node_root_urls
node_settings -->|"includes"| node_auth_app
node_settings -->|"includes"| node_sms_app
node_settings -->|"includes"| node_report_app
node_asgi -->|"uses"| node_settings
node_wsgi -->|"uses"| node_settings
node_root_urls -->|"routes"| node_auth_api
node_root_urls -->|"routes"| node_sms_api
node_root_urls -->|"routes"| node_report_views
node_auth_app -->|"implements"| node_auth_api
node_sms_app -->|"persists"| node_sms_domain
node_sms_app -->|"serves"| node_sms_api
node_sms_app -->|"processes"| node_sms_runner
node_report_app -->|"builds"| node_report_pipeline
node_report_app -->|"serves"| node_report_views
node_report_views -->|"renders"| node_report_templates
node_report_pipeline -->|"emits"| node_csv_exports
node_job_commands -->|"configures"| node_scheduler_store
node_job_commands -->|"runs"| node_sms_runner
node_job_commands -->|"runs"| node_report_pipeline
node_auth_api -->|"reads/writes"| node_orm_layer
node_sms_domain -->|"reads/writes"| node_orm_layer
node_report_app -->|"reads"| node_orm_layer
node_auth_api -.->|"protects"| node_sms_app
node_sms_api -.->|"feeds"| node_report_app

click node_manage_py "https://github.com/tamerhabbass/sms_lead_api/blob/main/manage.py"
click node_settings "https://github.com/tamerhabbass/sms_lead_api/blob/main/api/settings.py"
click node_root_urls "https://github.com/tamerhabbass/sms_lead_api/blob/main/api/urls.py"
click node_asgi "https://github.com/tamerhabbass/sms_lead_api/blob/main/api/asgi.py"
click node_wsgi "https://github.com/tamerhabbass/sms_lead_api/blob/main/api/wsgi.py"
click node_auth_app "https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/__init__.py"
click node_auth_api "https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/serializers.py"
click node_sms_app "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/__init__.py"
click node_sms_domain "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/models.py"
click node_sms_api "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/views.py"
click node_sms_runner "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/sms_run.py"
click node_report_app "https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/__init__.py"
click node_report_pipeline "https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/generate_report.py"
click node_report_views "https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/views.py"
click node_report_templates "https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/templates/reporting/reporting.html"
click node_csv_exports "https://github.com/tamerhabbass/sms_lead_api/blob/main/Rental_Forgiveness_2022-01-03 11_47_50_010741.csv"
click node_job_commands "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/management/commands/runapscheduler.py"
click node_scheduler_store "https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/management/commands/jobstores.py"
click node_orm_layer "https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/migrations/0001_initial.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_manage_py,node_settings,node_root_urls,node_asgi,node_wsgi,node_report_templates,node_csv_exports toneBlue
class node_auth_app,node_auth_api toneAmber
class node_sms_app,node_sms_domain,node_sms_api,node_sms_runner toneMint
class node_report_app,node_report_pipeline,node_report_views toneRose
class node_job_commands,node_scheduler_store toneIndigo
class node_orm_layer toneTeal
```

## Components

### Runtime

Django entrypoints and composition

- [manage.py](https://github.com/tamerhabbass/sms_lead_api/blob/main/manage.py): management entrypoint · Runs Django commands and scheduled tasks · `manage.py`
- [Settings](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/settings.py): django config · Central project configuration and app wiring · `api/settings.py`
- [Root URLs](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/urls.py): router · Top-level URL composition for all apps · `api/urls.py`
- [ASGI](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/asgi.py): async server entrypoint · Async deployment entrypoint · `api/asgi.py`
- [WSGI](https://github.com/tamerhabbass/sms_lead_api/blob/main/api/wsgi.py): server entrypoint · Traditional deployment entrypoint · `api/wsgi.py`

### Authentication

Identity and access layer

- [Auth App](https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/__init__.py): identity app · Authentication subsystem and custom API contract · `authentication/__init__.py`
- [Auth API](https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/serializers.py): serializers/views · Serializer, view, URL, renderer, and utility layer · `authentication/serializers.py`

### SMS Lead

Core lead and SMS business domain

- [SMS Lead App](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/__init__.py): domain app · Primary lead and SMS data domain · `sms_lead/__init__.py`
- [Lead Models](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/models.py): orm models · Lead/state persistence and business entities · `sms_lead/models.py`
- [Lead Views](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/views.py): request handlers · Lead-facing endpoints and request handling · `sms_lead/views.py`
- [SMS Runner](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/sms_run.py): dispatch logic · Encapsulates SMS send or message processing flow · `sms_lead/sms_run.py`

### Reporting

Report generation and presentation

- [Reporting App](https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/__init__.py): reporting app · Report generation and presentation subsystem · `reporting/__init__.py`
- [Report Pipeline](https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/generate_report.py): generation pipeline · Collects data, filters ranges, and builds reports · `reporting/generate_report.py`
- [Report Views](https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/views.py): views/forms · Server-rendered reporting endpoints and form handling · `reporting/views.py`

### Background Jobs

Scheduler and recurring command execution

- [Job Commands](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/management/commands/runapscheduler.py): scheduler commands · APSscheduler-style command entrypoints for recurring work · `sms_lead/management/commands/runapscheduler.py`
- [Job Stores](https://github.com/tamerhabbass/sms_lead_api/blob/main/sms_lead/management/commands/jobstores.py): scheduler config · Scheduler/job-store configuration and helpers · `sms_lead/management/commands/jobstores.py`

### Persistence

Django ORM models and migrations

- [ORM + Migrations](https://github.com/tamerhabbass/sms_lead_api/blob/main/authentication/migrations/0001_initial.py): persistence layer · Shared Django ORM persistence across app migrations · `authentication/migrations/0001_initial.py`

### Outputs

Rendered and exported artifacts

- [Report Templates](https://github.com/tamerhabbass/sms_lead_api/blob/main/reporting/templates/reporting/reporting.html): html/email templates · HTML pages and email subject templates for reporting · `reporting/templates/reporting/reporting.html`
- [CSV Exports](https://github.com/tamerhabbass/sms_lead_api/blob/HEAD/Rental_Forgiveness_2022-01-03%2011_47_50_010741.csv): report artifacts · Generated CSV outputs produced by reporting workflows · `Rental_Forgiveness_2022-01-03 11_47_50_010741.csv`

## Connections

- manage.py → Settings: loads · Bootstraps project configuration
- Settings → Root URLs: wires · Connects installed apps and routing
- Settings → Auth App: includes · Registers authentication subsystem
- Settings → SMS Lead App: includes · Registers SMS/lead subsystem
- Settings → Reporting App: includes · Registers reporting subsystem
- ASGI → Settings: uses · ASGI deployment loads project settings
- WSGI → Settings: uses · WSGI deployment loads project settings
- Root URLs → Auth API: routes · Dispatches auth endpoints
- Root URLs → Lead Views: routes · Dispatches lead endpoints
- Root URLs → Report Views: routes · Dispatches reporting endpoints
- Auth App → Auth API: implements · Authentication app owns its API contract
- SMS Lead App → Lead Models: persists · Lead data is stored in domain models
- SMS Lead App → Lead Views: serves · Lead request handlers live here
- SMS Lead App → SMS Runner: processes · SMS dispatch and processing logic
- Reporting App → Report Pipeline: builds · Report generation pipeline
- Reporting App → Report Views: serves · Rendered reporting endpoints
- Report Views → Report Templates: renders · HTML pages and email output
- Report Pipeline → CSV Exports: emits · Reporting can generate CSV artifacts
- Job Commands → Job Stores: configures · Recurring job execution setup
- Job Commands → SMS Runner: runs · Scheduler can trigger SMS processing
- Job Commands → Report Pipeline: runs · Scheduler can trigger reporting jobs
- Auth API → ORM + Migrations: reads/writes · Authentication has its own persisted schema
- Lead Models → ORM + Migrations: reads/writes · SMS lead models persist through Django ORM
- Reporting App → ORM + Migrations: reads · Reporting reads shared domain data
- Auth API → SMS Lead App: protects · Authentication gates access to domain endpoints
- Lead Views → Reporting App: feeds · Reporting depends on lead/domain data