# ananyap-wdw/adtestpro architecture

> Architecture diagram of the GitHub repository ananyap-wdw/adtestpro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ananyap-wdw/adtestpro
- Repository: https://github.com/ananyap-wdw/adtestpro

## Overview

##### Main Components

a) Frontend Layer:
- Web Interface (Templates directory indicates a server-side rendered application)
- Key pages: Dashboard, Persona Generation, Ad Creative Upload, Survey Management
- Templates structure showing the relationship between main pages and partials

b) Backend Layer:
- FastAPI/Python Application (indicated by the app structure)
- Core Processing Modules:
- Persona Generation Engine (audience.py)
- Analysis Engine (analyze.py)
- Experiment Management (experiment.py)
- Data Extraction Service (extract.py)

c) Database Layer:
- PostgreSQL Database (indicated by init-db.sql and alembic migrations)
- Alembic Migration System

d) External Services:
- OpenAI API Integration (mentioned in .env configuration)
- Image Processing Services (for ad creative analysis)

##### Analysis Pipeline Flow
- Ad Creative Upload → Visual Analysis → Information Extraction
- Target Audience Input → Persona Generation → Focus Group Simulation
- Results Collection → Analysis → Report Generation

##### Specific Architectural Elements

Key architectural patterns:
- MVC Pattern (evident from the templates and models separation)
- Service-based architecture (src directory structure)
- Prompt-driven processing (prompts directory)
- Database migration system (alembic)

**[User Interface Layer]**
- ↓
**[API Gateway/Router]**
- ↓
**[Core Services Layer]**
- Persona Generation
- Ad Analysis
- Focus Group Simulation
- Results Processing
- ↓
**[External Services Layer]**
- OpenAI API
- Image Processing
- ↓
**[Data Persistence Layer]**

##### Additional Elements

- Docker container boundaries (shown by Dockerfile and docker-compose.yml)
- API endpoints and their relationships
- Database schema references
- Prompt template management system
- Future scalability components (Redis, Celery - mentioned in TODO)

##### Technical Stack Indicators

- Python 3.11
- FastAPI
- PostgreSQL
- Docker
- OpenAI
- Alembic

This system design should clearly communicate both the current architecture and the planned scalability improvements mentioned in the TODO section.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interface Layer"]
        WI["Web Interface"]:::frontend
        DI["Dashboard Interface"]:::frontend
        PM["Persona Management"]:::frontend
        SM["Survey Management"]:::frontend
        SC["Survey Components"]:::frontend
        PC["Persona Components"]:::frontend
    end

    subgraph API["API Gateway"]
        FA["FastAPI Application"]:::api
        DM["Dependencies Manager"]:::api
    end

    subgraph Core["Core Services Layer"]
        PG["Persona Generation Engine"]:::service
        AE["Analysis Engine"]:::service
        EM["Experiment Management"]:::service
        DE["Data Extraction Service"]:::service
        CE["Core Processing Engine"]:::service
        PT["Prompt Templates"]:::service
        UT["Utility Functions"]:::service
        AC["API Client"]:::service
    end

    subgraph External["External Services"]
        OAI["OpenAI API"]:::external
        IP["Image Processing"]:::external
    end

    subgraph Data["Data Persistence Layer"]
        DB[(PostgreSQL Database)]:::database
        DBM["Database Models"]:::database
        DBI["Database Initialization"]:::database
        DBMig["Database Migrations"]:::database
    end

    %% UI Layer Connections
    WI --> FA
    DI --> FA
    PM --> FA
    SM --> FA
    SC --> SM
    PC --> PM

    %% API Layer Connections
    FA --> DM
    DM --> Core

    %% Core Service Connections
    PG --> OAI
    AE --> IP
    CE --> PG
    CE --> AE
    CE --> EM
    CE --> DE
    EM --> DB
    DE --> DB
    PT --> CE
    AC --> External

    %% Data Layer Connections
    DB --> DBM
    DBI --> DB
    DBMig --> DB

    %% Click Events
    click WI "https://github.com/AnanyaP-WDW/AdTestPro/tree/main/app/templates/"
    click DI "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/templates/dashboard.html"
    click PM "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/templates/view_personas.html"
    click SM "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/templates/run-focusgroup-survey.html"
    click SC "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/templates/partials/survey_questions.html"
    click PC "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/templates/partials/personas_table.html"
    click FA "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/main.py"
    click DM "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/dependencies.py"
    click PG "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/audience.py"
    click AE "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/analyze.py"
    click EM "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/experiment.py"
    click DE "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/extract.py"
    click CE "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/engine.py"
    click PT "https://github.com/AnanyaP-WDW/AdTestPro/tree/main/app/src/prompts/"
    click UT "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/utils.py"
    click AC "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/client.py"
    click DB "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/models/database.py"
    click DBM "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/app/src/models.py"
    click DBI "https://github.com/AnanyaP-WDW/AdTestPro/blob/main/docker-assets/init-db.sql"
    click DBMig "https://github.com/AnanyaP-WDW/AdTestPro/tree/main/app/migrations/alembic/"

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,stroke-width:2px
    classDef api fill:#2ecc71,stroke:#27ae60,stroke-width:2px
    classDef service fill:#e74c3c,stroke:#c0392b,stroke-width:2px
    classDef external fill:#f1c40f,stroke:#f39c12,stroke-width:2px
    classDef database fill:#9b59b6,stroke:#8e44ad,stroke-width:2px

    %% Legend
    subgraph Legend
        FE["Frontend Component"]:::frontend
        AP["API Component"]:::api
        SE["Service Component"]:::service
        EX["External Service"]:::external
        DA["Database Component"]:::database
    end
```
