How ogola5/marketing-app works
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.