How spark-data-team/nanga-ad-library works
Main Components
• Nanga Ad Library Core: This is the entry point (the SDK) that users import and interact with. Represent this as the central module (labeled “NangaAdLibrary”).
• Ad Library Modules: Found in “nanga_ad_library/ad_libraries”, these modules (for instance, meta_ad_library.py) act as the interface to individual platform APIs. They encapsulate platform-specific logic.
• Sessions and Connection Management: The “nanga_ad_library/sessions.py” module handles session creation and connection lifecycle management with external ad platforms.
• Utilities: The “nanga_ad_library/utils” directory (with files like ad_libraries_config.py, object_parser.py, param_checker.py, request_handler.py, and version.py) contains helper functions and configurations. Represent these as a shared library that is used by both the downloader and library modules.
• Exception Handling: The “nanga_ad_library/exceptions.py” file is dedicated to managing error scenarios.
• External Dependencies: The project relies on third-party libraries (e.g., Playwright for browser automation and likely packages for HTTP requests). Mark these as integration points. Also include external services such as the social media ad platforms (Facebook (Meta), potentially TikTok, Google, etc.) which are part of the system when deployed.
Relationships and Interactions
• The SDK then delegates tasks to the appropriate Ad Library module based on the platform specified (e.g., Meta).
• The Ad Library module will utilize an Ad Downloader module to fetch data from the external ad libraries.
• During data fetching, session management and utility functions (configurations, request handling, and parameter checking) are called to ensure a valid, robust connection and data extraction process.
• Exception handling is layered across the system to capture and manage errors that might occur during the download or API interaction phases.
Important Architectural Patterns
• Modularity: The file tree clearly separates concerns by dividing functionality among core SDK, downloader, and utility modules.
• Extensibility: The project is designed for future inclusion of more ad platforms (as seen in the Roadmap). The separation of downloader and library-specific modules supports the addition of new modules without affecting the core architecture.
• Abstraction: By using base or “meta” modules (e.g., meta_ad_downloader.py, meta_ad_library.py), the design abstracts the common functionality for different ad libraries, promoting reuse.
Incorporate Relevant Technologies and External Integrations
• Python Package Management: Setup via setup.py and MANIFEST.in, representing how the project is built and deployed.
• Playwright: Used for downloading ad elements (as shown in the README), represent it as an external tool or dependency that assists in browser-based data extraction.
• Social Media Platforms: Specifically represent Meta to start, with placeholders or extension points for other platforms (TikTok, Google, etc.) as per the roadmap.
• CI/CD Tools: The presence of GitHub workflows (for testing and releasing versions) should be represented as part of the development pipeline, although they may not be core to the runtime architecture.