# clachar94/humanbehaviorai architecture

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

- Interactive diagram: https://gitdiagram.com/clachar94/humanbehaviorai
- Repository: https://github.com/clachar94/humanbehaviorai

## Overview

#### Purpose and scope
Human Behavior AI is a data/AI project for detecting digital manipulation and artificial user behavior, especially bot accounts. Its repository is organized as a staged data pipeline plus phase-oriented analysis notebooks, rather than as a deployable application source tree.

#### Primary entry points
The executable pipeline is represented by ordered Python scripts:
- `scripts/01_carga.py`
- `scripts/02_limpieza.py`
- `scripts/03_procesamiento.py`

The scripts imply a sequential run order: ingest, clean, then transform/process. Exploratory, modeling, integration, and scalability work is captured in Jupyter notebooks, notably `notebooks/Fase3.ipynb`, `notebooks/Fase4.ipynb`, and `notebooks/Fase5_Integracion_Automatizacion.ipynb`.

#### Data ingestion and persistence
Raw bot-detection input is stored at `data/raw/bot_detection_data.csv`. The loading stage in `scripts/01_carga.py` is the boundary between file-based source data and downstream processing/storage.

A committed database artifact, `humanbehaviorai.db`, indicates local database persistence or experimentation. The README names PostgreSQL as the intended database technology, but no PostgreSQL schema, connection configuration, or deployment assets are present; engineers should validate whether the `.db` file is SQLite-derived and how it relates to the stated target database.

#### Data quality and feature-processing pipeline
`scripts/02_limpieza.py` is the data-quality boundary, responsible for converting raw records into a form suitable for analysis. `scripts/03_procesamiento.py` then performs the processing stage that produces the available processed dataset:
- `data/processed/bot_detection_procesado.csv`
- `data/raw/bot_detection_data.csv`

The processed CSV is the likely contract between ETL/preparation and model-analysis stages. Any automated rerun should preserve this raw-to-processed lineage and avoid treating the processed file as an independent source of truth.

#### Analytics and AI stages
Phase 4 notebooks contain the main analysis and AI work described by the project: anomaly detection and classification of automated accounts. Relevant artifacts include:
- `notebooks/Fase4.ipynb`
- `notebooks/Fase4_Analisis_e_IA.ipynb`
- `notebooks/Fase4 Etapas 1-2-5.ipynb`

Python, Pandas, and Scikit-Learn are the declared analytical runtime stack. Models and feature logic appear notebook-centered; there are no separate reusable model modules or serialized model artifacts in the tree.

#### Integration and operational evolution
Integration/automation and scalability are documented as later notebook phases:
- `notebooks/Fase5_Integracion_Automatizacion.ipynb`
- `notebooks/Fase6_Escalabilidad_Nube_Optimizacion.ipynb`
- `notebooks/Fase4_Etapas_1-2-5-6-7-8.ipynb`

These notebooks are the primary evidence of operational design, but the repository contains no visible scheduler, container, cloud infrastructure, CI workflow, API, or Streamlit application code. Streamlit and cloud/scalability should therefore be treated as intended or notebook-demonstrated capabilities, not established runtime entry points.

#### Key architectural boundaries
1. Source data: `data/raw/bot_detection_data.csv`.
2. ETL scripts: `scripts/01_carga.py` → `scripts/02_limpieza.py` → `scripts/03_procesamiento.py`.
3. Curated analytical dataset: `data/processed/bot_detection_procesado.csv`.
4. AI experimentation/modeling: Phase 4 notebooks.
5. Persistence and external-service boundary: `humanbehaviorai.db` locally, with PostgreSQL identified as the target external database technology.

The main modernization opportunity is to convert notebook-derived transformation and model logic into versioned Python modules, with explicit database contracts and a reproducible orchestration path.

Main entry points: [`notebooks/Fase4.ipynb`](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4.ipynb) (Phase 4 AI analysis), [`scripts/01_carga.py`](https://github.com/clachar94/humanbehaviorai/blob/main/scripts/01_carga.py) (Load), [`data/processed/bot_detection_procesado.csv`](https://github.com/clachar94/humanbehaviorai/blob/main/data/processed/bot_detection_procesado.csv) (Processed dataset), [`scripts/02_limpieza.py`](https://github.com/clachar94/humanbehaviorai/blob/main/scripts/02_limpieza.py) (Clean data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_etl["ETL Pipeline"]
  node_load["Load<br/>Python script<br/>[01_carga.py]"]
  node_clean["Clean data<br/>Python script<br/>[02_limpieza.py]"]
  node_process["Process data<br/>Python script"]
end

subgraph group_analytics["Analytics &amp; AI"]
  node_phase3["Phase 3 exploration<br/>Jupyter notebook<br/>[Fase3.ipynb]"]
  node_phase4["Phase 4 AI analysis<br/>Jupyter notebooks<br/>[Fase4.ipynb]"]
  node_phase4_analysis["Phase 4 analysis &amp; AI<br/>Jupyter notebook"]
  node_phase4_stages["Phase 4 stages<br/>Jupyter notebook"]
  node_python_stack["Python analytics stack<br/>Pandas + Scikit-Learn"]
  node_phase5["Integration &amp; automation<br/>Jupyter notebook"]
  node_phase6["Scalability &amp; cloud<br/>Jupyter notebook"]
  node_phase4_extended["Extended Phase 4 stages<br/>Jupyter notebook"]
end

node_raw_data["Raw bot dataset<br/>CSV source"]
node_processed_data["Processed dataset<br/>CSV contract"]
node_local_db[("Local DB artifact<br/>Database file<br/>[humanbehaviorai.db]")]
node_postgres_target[("PostgreSQL target<br/>Intended database")]

node_raw_data -->|"ingests"| node_load
node_load -->|"loaded records"| node_clean
node_clean -->|"cleaned records"| node_process
node_process -->|"writes"| node_processed_data
node_load -.->|"may persist"| node_local_db
node_local_db -.->|"target migration unclear"| node_postgres_target
node_processed_data -->|"explored by"| node_phase3
node_processed_data -->|"analysis input"| node_phase4
node_phase4 -.->|"complementary analysis"| node_phase4_analysis
node_phase4 -.->|"staged work"| node_phase4_stages
node_python_stack -->|"runtime"| node_phase4
node_phase4 -.->|"integration evolution"| node_phase5
node_phase5 -.->|"scalability evolution"| node_phase6
node_phase4 -.->|"extended stages"| node_phase4_extended

click node_raw_data "https://github.com/clachar94/humanbehaviorai/blob/main/data/raw/bot_detection_data.csv"
click node_load "https://github.com/clachar94/humanbehaviorai/blob/main/scripts/01_carga.py"
click node_clean "https://github.com/clachar94/humanbehaviorai/blob/main/scripts/02_limpieza.py"
click node_process "https://github.com/clachar94/humanbehaviorai/blob/main/scripts/03_procesamiento.py"
click node_processed_data "https://github.com/clachar94/humanbehaviorai/blob/main/data/processed/bot_detection_procesado.csv"
click node_local_db "https://github.com/clachar94/humanbehaviorai/blob/main/humanbehaviorai.db"
click node_phase3 "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase3.ipynb"
click node_phase4 "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4.ipynb"
click node_phase4_analysis "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4_Analisis_e_IA.ipynb"
click node_phase4_stages "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4%20Etapas%201-2-5.ipynb"
click node_phase5 "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase5_Integracion_Automatizacion.ipynb"
click node_phase6 "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase6_Escalabilidad_Nube_Optimizacion.ipynb"
click node_phase4_extended "https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4_Etapas_1-2-5-6-7-8.ipynb"

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_load,node_clean,node_process toneBlue
class node_phase3,node_phase4,node_phase4_analysis,node_phase4_stages,node_python_stack,node_phase5,node_phase6,node_phase4_extended toneAmber
class node_raw_data,node_processed_data,node_local_db,node_postgres_target toneNeutral
```

## Components

### ETL Pipeline

Ordered scripts transform source records into a curated dataset.

- [Load](https://github.com/clachar94/humanbehaviorai/blob/main/scripts/01_carga.py): Python script · Ingestion boundary from the source file. · `scripts/01_carga.py`
- [Clean data](https://github.com/clachar94/humanbehaviorai/blob/main/scripts/02_limpieza.py): Python script · Data-quality stage. · `scripts/02_limpieza.py`
- [Process data](https://github.com/clachar94/humanbehaviorai/blob/main/scripts/03_procesamiento.py): Python script · Transforms cleaned records for analysis. · `scripts/03_procesamiento.py`

### Analytics & AI

Notebook-centered analysis, modeling, and operational exploration.

- [Phase 3 exploration](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase3.ipynb): Jupyter notebook · `notebooks/Fase3.ipynb`
- [Phase 4 AI analysis](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4.ipynb): Jupyter notebooks · Anomaly detection and automated-account classification. · `notebooks/Fase4.ipynb`
- [Phase 4 analysis & AI](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4_Analisis_e_IA.ipynb): Jupyter notebook · `notebooks/Fase4_Analisis_e_IA.ipynb`
- [Phase 4 stages](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4%20Etapas%201-2-5.ipynb): Jupyter notebook · `notebooks/Fase4 Etapas 1-2-5.ipynb`
- **Python analytics stack**: Pandas + Scikit-Learn · Notebook runtime for feature work and models.
- [Integration & automation](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase5_Integracion_Automatizacion.ipynb): Jupyter notebook · Notebook-demonstrated operational design, not an established runtime. · `notebooks/Fase5_Integracion_Automatizacion.ipynb`
- [Scalability & cloud](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase6_Escalabilidad_Nube_Optimizacion.ipynb): Jupyter notebook · Explores intended scalability and cloud evolution. · `notebooks/Fase6_Escalabilidad_Nube_Optimizacion.ipynb`
- [Extended Phase 4 stages](https://github.com/clachar94/humanbehaviorai/blob/main/notebooks/Fase4_Etapas_1-2-5-6-7-8.ipynb): Jupyter notebook · `notebooks/Fase4_Etapas_1-2-5-6-7-8.ipynb`

### Other components

- [Raw bot dataset](https://github.com/clachar94/humanbehaviorai/blob/main/data/raw/bot_detection_data.csv): CSV source · `data/raw/bot_detection_data.csv`
- [Processed dataset](https://github.com/clachar94/humanbehaviorai/blob/main/data/processed/bot_detection_procesado.csv): CSV contract · Curated ETL output used by analytical stages. · `data/processed/bot_detection_procesado.csv`
- [Local DB artifact](https://github.com/clachar94/humanbehaviorai/blob/main/humanbehaviorai.db): Database file · Persistence or experimentation artifact; database engine needs validation. · `humanbehaviorai.db`
- **PostgreSQL target**: Intended database · Named as target technology, without repository schema or connection assets.

## Connections

- Raw bot dataset → Load: ingests
- Load → Clean data: loaded records
- Clean data → Process data: cleaned records
- Process data → Processed dataset: writes
- Load → Local DB artifact: may persist
- Local DB artifact → PostgreSQL target: target migration unclear
- Processed dataset → Phase 3 exploration: explored by
- Processed dataset → Phase 4 AI analysis: analysis input
- Phase 4 AI analysis → Phase 4 analysis & AI: complementary analysis
- Phase 4 AI analysis → Phase 4 stages: staged work
- Python analytics stack → Phase 4 AI analysis: runtime
- Phase 4 AI analysis → Integration & automation: integration evolution
- Integration & automation → Scalability & cloud: scalability evolution
- Phase 4 AI analysis → Extended Phase 4 stages: extended stages
