# ogola5/marketing-app architecture

> Architecture diagram of the GitHub repository ogola5/marketing-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ogola5/marketing-app
- Repository: https://github.com/ogola5/marketing-app

## Overview

##### Project Type and Purpose
- This is a full-stack AI-driven marketing/SEO automation application (“Emergent”).
- Frontend: React single-page app for user onboarding, authentication, campaign management, dashboard, and modals.
- Backend: Python FastAPI service exposing REST endpoints for auth, campaigns, leads, domains, SEO operations, system health, with business logic in “services” and a scheduler for background jobs.
- Database: Likely MongoDB (presence of pymongo, motor, gridfs) for storing users, campaigns, leads, domain data, models, and content artifacts.
- External Integrations: AI/ML APIs (Hugging Face), email (SMTP), crawler engines, fundability checker, geo-intent resolver, third-party SEO tools.

##### Main Components
- Frontend (React/Tailwind)
- Components folder: AuthComponent, Login, Onboarding, Dashboard, CampaignModal
- Interacts with backend via HTTP/HTTPS REST API
- API Gateway / Backend (FastAPI)
- Entry: backend/main.py → uvicorn or Gunicorn server
- Routes: auth.py, campaigns.py, leads.py, domain.py, seo.py, system.py, dashboard.py
- Services: business logic modules (ai_service, crawler_service, email_service, injection_engine, seo_brainstorm, etc.)
- Models: ORM or ODM schemas (User, Campaign, Lead, Domain, E3TModel)
- Utils: helpers, content optimizer, security, validators, schema generator
- Config: settings.py, database.py for environment & connection setup
- Database (MongoDB)
- Collections: users, campaigns, leads, domains, content models
- Driver: motor or pymongo
- GridFS: storing binary assets if needed
- Scheduler / Background Worker
- backend/scheduler.py: periodic tasks (crawl jobs, email blasts, campaign evaluations)
- May run in a separate process or thread pool
- External Services
- AI/ML endpoints: hugging-face models, custom ML evaluators
- Email server (SMTP)
- Web crawling infrastructure
- Third-party APIs for SEO/fundability/geo-intent

##### Relationships & Data Flows
- User → Frontend (React) → HTTP(S) → API Gateway (FastAPI)
- API Gateway
- Auth requests → auth_service → database (users)
- Campaign CRUD → campaign_service → database (campaigns)
- SEO brainstorming → seo_brainstorm → AI API → returns suggestions
- Crawler requests → crawler_service → external websites → database (domain/lead data)
- Email dispatch → email_service → SMTP server
- Scheduler
- Triggers background jobs (e.g., nightly crawl, content evaluation)
- Uses same service layer but runs asynchronously
- Database
- All persistent reads/writes happen here
- Services import database client for transactions
- Tests
- Simple unit tests at root (backend_test.py, comprehensive_test.py)
- Integration tests (gemini_integration_test.py, simple_gemini_test.py)

##### Architectural Patterns & Principles
- Layered architecture:
- Presentation (frontend)
- API/Routes (controllers)
- Service layer (business logic)
- Data layer (models + database)
- Dependency injection via FastAPI’s DI system
- Asynchronous I/O for crawler, AI calls, DB access
- Separation of concerns: each service focuses on a domain function
- Scheduler decoupled from request-driven API

##### Essential Elements
- Clear labels on all components (e.g., “AuthComponent”, “campaign_service”).
- Annotations for asynchronous flow where appropriate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend UI Layer
    subgraph "Frontend (UI)" 
        direction TB
        User["User"]:::ui
        ReactApp["React App"]:::ui
        AuthComp["AuthComponent"]:::ui
        LoginComp["LoginComponent"]:::ui
        OnboardingComp["OnboardingComponent"]:::ui
        DashboardComp["DashboardComponent"]:::ui
        CampaignModal["CampaignModal"]:::ui
    end

    %% Backend API Gateway
    subgraph "Backend (FastAPI)" 
        direction TB

        subgraph "Config"
            direction TB
            Settings["settings.py"]:::data
            DbConfig["database.py"]:::data
        end

        subgraph "Routes (Controllers)" 
            direction TB
            AuthRoute["auth.py"]:::api
            CampaignRoute["campaigns.py"]:::api
            LeadsRoute["leads.py"]:::api
            DomainRoute["domain.py"]:::api
            SEORoute["seo.py"]:::api
            DashboardRoute["dashboard.py"]:::api
            SystemRoute["system.py"]:::api
        end

        subgraph "Services (Business Logic)"
            direction TB
            AIService["ai_service.py"]:::service
            AuthService["auth_service.py"]:::service
            CampaignService["campaign_service.py"]:::service
            CrawlerService["crawler_service.py"]:::service
            EmailService["email_service.py"]:::service
            InjectionEngine["injection_engine.py"]:::service
            SEOBRAIN["seo_brainstorm.py"]:::service
            FundChecker["fundability_checker.py"]:::service
            GeoIntent["geo_intent_resolver.py"]:::service
            E3TEval["e3t_evaluator.py"]:::service
            DomainService["domain_service.py"]:::service
            IntentMatcher["intent_matcher.py"]:::service
            ConsoleService["console_service.py"]:::service
        end

        subgraph "Utils"
            direction TB
            Constants["constants.py"]:::data
            Helpers["helpers.py"]:::data
            ContentOpt["content_optimizer.py"]:::data
            HFAPI["hf_api.py"]:::data
            SchemaGen["schema_generator.py"]:::data
            SecurityUtil["security.py"]:::data
            Validators["validators.py"]:::data
        end

        MainEntry["main.py"]:::api
        AppRunner["run.py"]:::api
        ServerSetup["server.py"]:::api
    end

    %% Database
    subgraph "Database (MongoDB)"
        direction TB
        DB["MongoDB"]:::data
    end

    %% Scheduler
    Scheduler["Scheduler\n(scheduler.py)"]:::sched

    %% External Services
    subgraph "External Services"
        direction TB
        AIAPI["AI/ML API"]:::ext
        SMTP["SMTP Server"]:::ext
        CrawlerWeb["Web Crawling"]:::ext
        SEOtools["Third-Party SEO APIs"]:::ext
    end

    %% Tests
    subgraph "Tests"
        direction TB
        UnitTests["backend_test.py\ncomprehensive_test.py"]:::test
        IntegrationTests["gemini_integration_test.py\nsimple_gemini_test.py"]:::test
        TestSuite["tests/"]:::test
    end

    %% Connections
    User -->|"interacts with"| ReactApp
    ReactApp -->|"HTTPS/REST"| AuthRoute
    ReactApp -->|"HTTPS/REST"| CampaignRoute
    ReactApp -->|"HTTPS/REST"| SEORoute

    AuthRoute -->|"calls"| AuthService
    CampaignRoute -->|"calls"| CampaignService
    SEORoute -->|"calls"| SEOBRAIN

    AuthService -->|"async MongoDB driver"| DB
    CampaignService -->|"async MongoDB driver"| DB
    CrawlerService -->|"HTTP"| CrawlerWeb
    EmailService -->|"SMTP"| SMTP
    SEOBRAIN -->|"HTTPS"| AIAPI
    CampaignService -->|"async MongoDB driver"| DB

    Scheduler -->|"schedules jobs on"| CampaignService
    Scheduler -->|"schedules jobs on"| CrawlerService
    Scheduler -->|"schedules jobs on"| EmailService

    DbConfig -->|imports| MainEntry
    Settings -->|imports| MainEntry

    MainEntry -->|runs| ServerSetup
    MainEntry -->|runs| AppRunner

    MainEntry -->|includes routes| AuthRoute
    MainEntry -->|includes routes| CampaignRoute
    MainEntry -->|includes routes| LeadsRoute
    MainEntry -->|includes routes| DomainRoute
    MainEntry -->|includes routes| SEORoute
    MainEntry -->|includes routes| DashboardRoute
    MainEntry -->|includes routes| SystemRoute

    %% Tests connections
    UnitTests -->|tests| AuthService
    UnitTests -->|tests| CampaignService
    IntegrationTests -->|tests| AIAPI

    %% Click Events for component mapping
    click ReactApp "https://github.com/ogola5/marketing-app/blob/main/frontend/src/index.js"
    click MainEntry "https://github.com/ogola5/marketing-app/blob/main/backend/main.py"
    click AppRunner "https://github.com/ogola5/marketing-app/blob/main/backend/run.py"
    click ServerSetup "https://github.com/ogola5/marketing-app/blob/main/backend/server.py"

    click Settings "https://github.com/ogola5/marketing-app/blob/main/backend/config/settings.py"
    click DbConfig "https://github.com/ogola5/marketing-app/blob/main/backend/config/database.py"

    click AuthRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/auth.py"
    click CampaignRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/campaigns.py"
    click LeadsRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/leads.py"
    click DomainRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/domain.py"
    click SEORoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/seo.py"
    click DashboardRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/dashboard.py"
    click SystemRoute "https://github.com/ogola5/marketing-app/blob/main/backend/routes/system.py"

    click AIService "https://github.com/ogola5/marketing-app/blob/main/backend/services/ai_service.py"
    click AuthService "https://github.com/ogola5/marketing-app/blob/main/backend/services/auth_service.py"
    click CampaignService "https://github.com/ogola5/marketing-app/blob/main/backend/services/campaign_service.py"
    click CrawlerService "https://github.com/ogola5/marketing-app/blob/main/backend/services/crawler_service.py"
    click EmailService "https://github.com/ogola5/marketing-app/blob/main/backend/services/email_service.py"
    click InjectionEngine "https://github.com/ogola5/marketing-app/blob/main/backend/services/injection_engine.py"
    click SEOBRAIN "https://github.com/ogola5/marketing-app/blob/main/backend/services/seo_brainstorm.py"
    click FundChecker "https://github.com/ogola5/marketing-app/blob/main/backend/services/fundability_checker.py"
    click GeoIntent "https://github.com/ogola5/marketing-app/blob/main/backend/services/geo_intent_resolver.py"
    click E3TEval "https://github.com/ogola5/marketing-app/blob/main/backend/services/e3t_evaluator.py"
    click DomainService "https://github.com/ogola5/marketing-app/blob/main/backend/services/domain_service.py"
    click IntentMatcher "https://github.com/ogola5/marketing-app/blob/main/backend/services/intent_matcher.py"
    click ConsoleService "https://github.com/ogola5/marketing-app/blob/main/backend/services/console_service.py"

    click Constants "https://github.com/ogola5/marketing-app/blob/main/backend/utils/constants.py"
    click Helpers "https://github.com/ogola5/marketing-app/blob/main/backend/utils/helpers.py"
    click ContentOpt "https://github.com/ogola5/marketing-app/blob/main/backend/utils/content_optimizer.py"
    click HFAPI "https://github.com/ogola5/marketing-app/blob/main/backend/utils/hf_api.py"
    click SchemaGen "https://github.com/ogola5/marketing-app/blob/main/backend/utils/schema_generator.py"
    click SecurityUtil "https://github.com/ogola5/marketing-app/blob/main/backend/utils/security.py"
    click Validators "https://github.com/ogola5/marketing-app/blob/main/backend/utils/validators.py"

    click Scheduler "https://github.com/ogola5/marketing-app/blob/main/backend/scheduler.py"

    click UnitTests "https://github.com/ogola5/marketing-app/blob/main/backend_test.py"
    click IntegrationTests "https://github.com/ogola5/marketing-app/blob/main/gemini_integration_test.py"
    click TestSuite "https://github.com/ogola5/marketing-app/tree/main/tests/"

    %% UI component clicks
    click AuthComp "https://github.com/ogola5/marketing-app/blob/main/frontend/src/components/AuthComponent.js"
    click LoginComp "https://github.com/ogola5/marketing-app/blob/main/frontend/src/components/LoginComponent.js"
    click OnboardingComp "https://github.com/ogola5/marketing-app/blob/main/frontend/src/components/OnboardingComponent.js"
    click DashboardComp "https://github.com/ogola5/marketing-app/blob/main/frontend/src/components/DashboardComponent.js"
    click CampaignModal "https://github.com/ogola5/marketing-app/blob/main/frontend/src/components/CampaignModal.js"

    %% Data Models
    classDef ui fill:#cce5ff,stroke:#339af0
    classDef api fill:#d4edda,stroke:#28a745
    classDef service fill:#fff3cd,stroke:#ffc107
    classDef data fill:#dee2e6,stroke:#6c757d
    classDef ext fill:#f8d7da,stroke:#dc3545
    classDef sched fill:#e2e3e5,stroke:#6c757d
    classDef test fill:#e2e3e5,stroke:#6c757d

    %% Legend
    subgraph Legend
        direction LR
        L1["UI Components"]:::ui
        L2["API Routes"]:::api
        L3["Services"]:::service
        L4["Data / Config"]:::data
        L5["External"]:::ext
        L6["Scheduler / Tests"]:::sched
    end
```
