# alejandrotejero/webbuilder-tfg architecture

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

- Interactive diagram: https://gitdiagram.com/alejandrotejero/webbuilder-tfg
- Repository: https://github.com/alejandrotejero/webbuilder-tfg

## Overview

#### Purpose and entry points
WebBuilder is a Django 5.1 platform that turns a public JSON/XML/CSV API into a generated, deployable Django website. HTTP routing begins in `project/urls.py` and app routes in `WebBuilder/urls.py`; deployment entry points are `manage.py`, `project/wsgi.py`, and `project/asgi.py`.

#### Core Django application
The `WebBuilder` app owns user-facing workflows, persistence, and server-rendered UI. Domain records likely cover API analyses, generated sites, versions, logs, users, and profiles, as reflected in `WebBuilder/models.py` and the cumulative migrations under `WebBuilder/migrations/`. Views are divided by workflow: assistant, editing, site rendering, history, metrics, authentication, and internal endpoints in `WebBuilder/views/`.

#### Assisted API-to-plan pipeline
The generation assistant accepts an API URL, fetches and safely parses source data, then produces an editable structured plan. Ingestion supports URL reading and JSON/XML/CSV parsing through `WebBuilder/utils/ingest/url_reader.py` and `WebBuilder/utils/ingest/parsers.py`. Dataset analysis—including detection, field-role inference, and plan construction—is separated under `WebBuilder/utils/analysis/builder.py`, `WebBuilder/utils/analysis/detection.py`, and `WebBuilder/utils/analysis/field_roles.py`.

#### LLM abstraction and planning
LLM calls are centralized behind an OpenAI-compatible client, allowing providers such as Groq, OpenRouter, or OpenAI. Planning, prompt enrichment, field extraction, design presets, and output consistency checking are distinct stages in `WebBuilder/utils/llm/client.py`, `WebBuilder/utils/llm/planner.py`, and `WebBuilder/utils/llm/consistency_checker.py`. User-specific API keys are an important security boundary, with encrypted-field support described by configuration and persistence.

#### Project generation and versioning
After plan approval, the generator creates a standalone Django project: code, templates, static assets, migrations, data-loading support, and packaging/deployment artifacts. The main orchestration and generated-project assembly live in `WebBuilder/utils/generator/project_generator.py`, with migration/static-file generation in `WebBuilder/utils/generator/migrations_generator.py` and `WebBuilder/utils/generator/static_files.py`. Generated-site versions enable review, editing, restoration, download, and AI-assisted file refinement through `WebBuilder/views/edit.py` and `WebBuilder/views/site.py`.

#### Web interface and operational views
The product is server-rendered Django HTML with page-specific JavaScript/CSS, not a separate SPA. The guided assistant is rooted at `WebBuilder/templates/WebBuilder/assistant.html`, with staged partials under `WebBuilder/templates/WebBuilder/partials/assistant/`; browser orchestration is in `WebBuilder/static/js/assistant.js`. History, code editor, public site preview, and metrics have dedicated views/templates under `WebBuilder/views/` and `WebBuilder/templates/WebBuilder/`.

#### Runtime, deployment, and integrations
Production infrastructure is Docker Compose with Django/Gunicorn, PostgreSQL, Nginx, and n8n. Definitions reside in `deploy/docker-compose.yml`, `deploy/Dockerfile`, and `deploy/nginx/nginx.conf`. Django invokes n8n webhooks for generated-site deployment, notifications, health checks, and automatic shutdown; n8n has Docker-host access to build and run generated projects. Authentication uses `django-allauth` with optional Google/GitHub OAuth; localization is maintained under `locale/`.

Main entry points: [`WebBuilder/utils/generator/project_generator.py`](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/project_generator.py) (Project generator), [`WebBuilder/utils/llm/planner.py`](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/planner.py) (LLM planner), [`project/urls.py`](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/project/urls.py) (Django entry points), [`WebBuilder/views/edit.py`](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/views/edit.py) (Generated site versions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Django WebBuilder"]
  node_django_entry{{"Django entry points<br/>Django runtime<br/>[urls.py]"}}
  node_app_routes["WebBuilder routes<br/>URL routing<br/>[urls.py]"]
  node_workflow_views["Workflow views<br/>Django views"]
  node_domain_models[("Domain records<br/>Django models<br/>[models.py]")]
  node_assistant_ui["Assistant UI<br/>Django template<br/>[assistant.html]"]
  node_assistant_browser["Assistant browser flow<br/>JavaScript<br/>[assistant.js]"]
end

subgraph group_pipeline["API-to-Plan Pipeline"]
  node_url_ingestion["URL ingestion<br/>data ingestion<br/>[url_reader.py]"]
  node_dataset_analysis["Dataset analysis<br/>analysis pipeline<br/>[builder.py]"]
end

subgraph group_llm["LLM Planning"]
  node_llm_client{{"OpenAI-compatible client<br/>LLM gateway<br/>[client.py]"}}
  node_llm_planner["LLM planner<br/>planning stage<br/>[planner.py]"]
  node_consistency_check["Plan consistency check<br/>validation stage"]
end

subgraph group_generation["Site Generation"]
  node_project_generator["Project generator<br/>generation orchestrator"]
  node_migration_generator["Generated migrations<br/>code generator"]
  node_static_generator["Generated static assets<br/>asset generator<br/>[static_files.py]"]
  node_site_versions["Generated site versions<br/>versioned artifacts<br/>[edit.py]"]
end

subgraph group_ops["Deployment &amp; Integrations"]
  node_compose_stack["Production Compose stack<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_nginx["Nginx proxy<br/>reverse proxy<br/>[nginx.conf]"]
  node_n8n{{"n8n automation<br/>webhook automation"}}
end

node_django_entry -->|"dispatches"| node_app_routes
node_app_routes -->|"routes requests"| node_workflow_views
node_workflow_views -->|"reads and writes"| node_domain_models
node_assistant_ui -->|"drives"| node_assistant_browser
node_assistant_browser -->|"assistant requests"| node_workflow_views
node_workflow_views -->|"submits API URL"| node_url_ingestion
node_url_ingestion -->|"parsed dataset"| node_dataset_analysis
node_dataset_analysis -->|"analysis and draft plan"| node_llm_planner
node_llm_planner -->|"provider calls"| node_llm_client
node_llm_planner -->|"validates output"| node_consistency_check
node_consistency_check -->|"editable plan"| node_workflow_views
node_workflow_views -->|"approved plan"| node_project_generator
node_project_generator -->|"generates schema"| node_migration_generator
node_project_generator -->|"generates assets"| node_static_generator
node_project_generator -->|"creates version"| node_site_versions
node_site_versions -->|"version metadata"| node_domain_models
node_compose_stack -->|"runs application"| node_django_entry
node_nginx -->|"proxies HTTP"| node_django_entry
node_workflow_views -->|"deployment webhooks"| node_n8n
node_n8n -->|"builds and runs sites"| node_site_versions

click node_django_entry "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/project/urls.py"
click node_app_routes "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/urls.py"
click node_domain_models "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/models.py"
click node_assistant_ui "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/templates/WebBuilder/assistant.html"
click node_assistant_browser "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/static/js/assistant.js"
click node_url_ingestion "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/ingest/url_reader.py"
click node_dataset_analysis "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/analysis/builder.py"
click node_llm_client "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/client.py"
click node_llm_planner "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/planner.py"
click node_consistency_check "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/consistency_checker.py"
click node_project_generator "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/project_generator.py"
click node_migration_generator "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/migrations_generator.py"
click node_static_generator "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/static_files.py"
click node_site_versions "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/views/edit.py"
click node_compose_stack "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/deploy/docker-compose.yml"
click node_nginx "https://github.com/alejandrotejero/webbuilder-tfg/blob/master/deploy/nginx/nginx.conf"

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_django_entry,node_app_routes,node_workflow_views,node_domain_models,node_assistant_ui,node_assistant_browser toneBlue
class node_url_ingestion,node_dataset_analysis toneAmber
class node_llm_client,node_llm_planner,node_consistency_check toneMint
class node_project_generator,node_migration_generator,node_static_generator,node_site_versions toneRose
class node_compose_stack,node_nginx,node_n8n toneIndigo
```

## Components

### Django WebBuilder

Server-rendered product workflows and persistence.

- [Django entry points](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/project/urls.py): Django runtime · HTTP routing and WSGI/ASGI deployment entry points. · `project/urls.py`
- [WebBuilder routes](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/urls.py): URL routing · `WebBuilder/urls.py`
- **Workflow views**: Django views · Assistant, editing, preview, history, metrics, auth, and internal endpoints.
- [Domain records](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/models.py): Django models · Stores analyses, sites, versions, logs, users, profiles, and encrypted key material. · `WebBuilder/models.py`
- [Assistant UI](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/templates/WebBuilder/assistant.html): Django template · Guided plan-creation interface with staged partials. · `WebBuilder/templates/WebBuilder/assistant.html`
- [Assistant browser flow](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/static/js/assistant.js): JavaScript · `WebBuilder/static/js/assistant.js`

### API-to-Plan Pipeline

Ingests public data and produces editable plans.

- [URL ingestion](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/ingest/url_reader.py): data ingestion · Fetches API sources and safely parses JSON, XML, or CSV. · `WebBuilder/utils/ingest/url_reader.py`
- [Dataset analysis](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/analysis/builder.py): analysis pipeline · Detects datasets, infers field roles, and constructs plans. · `WebBuilder/utils/analysis/builder.py`

### LLM Planning

Provider-neutral AI planning and validation.

- [OpenAI-compatible client](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/client.py): LLM gateway · Central provider abstraction for Groq, OpenRouter, and OpenAI. · `WebBuilder/utils/llm/client.py`
- [LLM planner](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/planner.py): planning stage · Enriches prompts, extracts fields, and applies design presets. · `WebBuilder/utils/llm/planner.py`
- [Plan consistency check](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/llm/consistency_checker.py): validation stage · `WebBuilder/utils/llm/consistency_checker.py`

### Site Generation

Builds and versions standalone Django sites.

- [Project generator](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/project_generator.py): generation orchestrator · Assembles a standalone Django project and deployment package. · `WebBuilder/utils/generator/project_generator.py`
- [Generated migrations](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/migrations_generator.py): code generator · `WebBuilder/utils/generator/migrations_generator.py`
- [Generated static assets](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/utils/generator/static_files.py): asset generator · `WebBuilder/utils/generator/static_files.py`
- [Generated site versions](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/WebBuilder/views/edit.py): versioned artifacts · Supports review, editing, restoration, download, and AI refinement. · `WebBuilder/views/edit.py`

### Deployment & Integrations

Production stack and deployment automation.

- [Production Compose stack](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/deploy/docker-compose.yml): Docker Compose · Runs Django/Gunicorn, PostgreSQL, Nginx, and n8n. · `deploy/docker-compose.yml`
- [Nginx proxy](https://github.com/alejandrotejero/webbuilder-tfg/blob/master/deploy/nginx/nginx.conf): reverse proxy · `deploy/nginx/nginx.conf`
- **n8n automation**: webhook automation · Deploys generated sites and handles notifications, health checks, and shutdown.

## Connections

- Django entry points → WebBuilder routes: dispatches
- WebBuilder routes → Workflow views: routes requests
- Workflow views → Domain records: reads and writes
- Assistant UI → Assistant browser flow: drives
- Assistant browser flow → Workflow views: assistant requests
- Workflow views → URL ingestion: submits API URL
- URL ingestion → Dataset analysis: parsed dataset
- Dataset analysis → LLM planner: analysis and draft plan
- LLM planner → OpenAI-compatible client: provider calls
- LLM planner → Plan consistency check: validates output
- Plan consistency check → Workflow views: editable plan
- Workflow views → Project generator: approved plan
- Project generator → Generated migrations: generates schema
- Project generator → Generated static assets: generates assets
- Project generator → Generated site versions: creates version
- Generated site versions → Domain records: version metadata
- Production Compose stack → Django entry points: runs application
- Nginx proxy → Django entry points: proxies HTTP
- Workflow views → n8n automation: deployment webhooks
- n8n automation → Generated site versions: builds and runs sites