What Is the Purpose of the Root Directory in TrendRadar? A Deep Dive into the Project Structure

The root directory in TrendRadar serves as the central integration hub that exposes the package, holds configuration and assets, and provides deployment scripts that transform the source code into a runnable hotspot-monitoring application.

The purpose of the root directory in TrendRadar is to act as the project façade—the single location that wires together every component and makes the tool usable out-of-the-box. This article examines how the root directory in TrendRadar coordinates the package entry points, user documentation, configuration files, deployment artifacts, and runtime outputs that power this open-source trend monitoring system.

Package Entry Points: How TrendRadar Exposes Its API

The root directory contains the trendradar/ package subdirectory, which houses the critical entry points that make the application executable.

trendradar/__init__.py: Public API Declaration

This file declares the package version and exports AppContext, making these components available to external callers:

from trendradar import AppContext, __version__

trendradar/__main__.py: CLI Orchestration

The __main__.py file implements the command-line interface, enabling execution via python -m trendradar. This module orchestrates the entire run cycle:

• Loading configuration from config/config.yaml
• Crawling platforms for trending content
• Analyzing data with AI filters
• Rendering HTML reports
• Sending notifications through configured channels
• Handling version checks

The root directory's placement of these files ensures the package is both importable as a library and runnable as a standalone application.

Configuration Management: Centralized Control in the Root

The root directory in TrendRadar serves as the single source of truth for runtime behavior through its config/ subdirectory.

Core Configuration Files

File	Purpose
config/config.yaml	Primary runtime configuration (platforms, schedule, notifications, AI settings)
config/timeline.yaml	Time-slot-based schedule driving the unified scheduler
config/frequency_words.txt	Word frequency filters for content analysis
config/ai_*.txt	AI prompt templates and filter configurations

These centralized, versioned defaults make the root directory the configuration hub that the runtime consults to determine what to crawl, when to run, and where to push results.

Runtime Configuration Override

The AppContext class supports environment-based overrides without modifying repository files:

# Use external configuration while keeping the repo clean

export TREND_RADAR_CONFIG=/path/to/my_config.yaml
python -m trendradar

This design preserves the root directory's role as the default configuration source while enabling flexible deployments.

Deployment Artifacts: From Source to Running System

The root directory transforms TrendRadar from source code into a deployable application through its deployment scripts and container definitions.

Container Deployment

The docker/ subdirectory contains reproducible deployment configurations:

# Start the complete stack from the root directory

docker compose -f docker/docker-compose.yml up -d

The docker/Dockerfile builds a container with the application and its dependencies, while docker-compose.yml orchestrates the main service with optional MCP AI service integration.

Convenience Scripts

Script	Function
start-http.sh	Launches the built-in web server for HTML reports
setup-*.sh	Environment-specific installation scripts

These root-level scripts enable one-command deployment operations that reference the package, configuration, and output directories.

Dependency Management

The root directory specifies dependencies through:

• requirements.txt — pip-compatible dependency list
• pyproject.toml — modern Python packaging standards

These files enable installation via pip install -e . for development or production deployments.

Static Assets and Web Interface

The root directory contains the generated HTML report and supporting assets that make TrendRadar's output immediately viewable.

Key Static Files

• index.html — Generated HTML report (updated at runtime)
• _image/ — Banner, icons, and UI assets referenced by reports
• docs/assets/ — Documentation site resources

This placement ensures the HTML report is self-contained — images and stylesheets reside alongside the source code, making the output directory portable and viewable without external dependencies.

Data Storage and Runtime Outputs

The root directory defines the default location for all runtime-generated data through the output/ subdirectory (created at runtime).

Output Contents

Data Type	Location	Purpose
SQLite databases	output/*.db	Structured storage of crawled content and trends
CSV snapshots	output/*.csv	Exportable data extracts
HTML reports	output/index.html	Final rendered visualization

The storage manager (trendradar/storage/...) hard-codes this relative path, making the root directory the anchor point for all persistent data.

Practical Usage Examples

Running TrendRadar from the Root Directory

# Install in editable mode

pip install -e .

# Execute the full pipeline

python -m trendradar

This executes trendradar/__main__.py, which loads config/config.yaml, crawls platforms, builds output/index.html, and sends configured notifications.

Generating Reports Without Notifications

python -m trendradar --report-only
xdg-open output/index.html  # Linux/macOS

The --report-only flag skips notification pipelines, creating only the HTML output in the root's output/ directory.

Docker Deployment from Root

# Mounts current directory (root) into container

docker compose -f docker/docker-compose.yml up -d

The compose file mounts ./ to make the trendradar package, config/ files, and output/ directory available to the containerized process.

Summary

The root directory in TrendRadar serves five critical architectural purposes:

• Package exposure — Contains trendradar/ with __init__.py and __main__.py for importable library and executable CLI functionality
• Configuration hub — Houses config/ with centralized YAML files that control runtime behavior across all components
• Deployment orchestration — Provides docker/, shell scripts, and dependency files for one-command container or local deployment
• Asset hosting — Contains index.html, _image/, and documentation assets for self-contained report generation
• Data anchor — Defines the output/ directory for all runtime-generated databases, CSVs, and HTML reports

All sub-modules — crawler, storage, AI analysis, notification — are referenced from this root, making it the single source of truth for TrendRadar's application structure.

Frequently Asked Questions

What files are required in the root directory to run TrendRadar?

The essential files are trendradar/__init__.py and trendradar/__main__.py for the package entry points, plus config/config.yaml for runtime configuration. The requirements.txt or pyproject.toml files are needed for dependency installation. While output/ is created automatically at runtime, having write permissions in the root directory is required for data storage.

Can I change the default configuration location without modifying the repository?

Yes. Set the TREND_RADAR_CONFIG environment variable to point to an external YAML file. The AppContext class in trendradar/__init__.py checks this environment variable and loads the specified configuration instead of the default config/config.yaml in the root directory.

Why does TrendRadar place the generated HTML report in the root directory?

The index.html file in the root serves as the default landing point for the generated report, making it immediately discoverable. The output/ subdirectory contains historical data, backups, and archived reports. This structure keeps the current report accessible at the repository root while organizing historical artifacts in a dedicated folder. The start-http.sh script in the root launches a local server that serves index.html by default.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}