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

> Discover the purpose of the root directory in TrendRadar. Learn how it integrates the package, manages configurations, and deploys the hotspot-monitoring application.

- Repository: [sansan/TrendRadar](https://github.com/sansan0/TrendRadar)
- Tags: deep-dive
- Published: 2026-04-22

---

**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`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__init__.py): Public API Declaration

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

```python
from trendradar import AppContext, __version__

```

### [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py): CLI Orchestration

The [`__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/__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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) | Primary runtime configuration (platforms, schedule, notifications, AI settings) |
| [`config/timeline.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/timeline.yaml) | Time-slot-based schedule driving the unified scheduler |
| [`config/frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/sansan0/TrendRadar/blob/main/docker-compose.yml) orchestrates the main service with optional MCP AI service integration.

### Convenience Scripts

| Script | Function |
|--------|----------|
| [`start-http.sh`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/requirements.txt) — pip-compatible dependency list
- [`pyproject.toml`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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

```bash

# Install in editable mode

pip install -e .

# Execute the full pipeline

python -m trendradar

```

This executes [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py), which loads [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml), crawls platforms, builds [`output/index.html`](https://github.com/sansan0/TrendRadar/blob/main/output/index.html), and sends configured notifications.

### Generating Reports Without Notifications

```bash
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

```bash

# 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`](https://github.com/sansan0/TrendRadar/blob/main/__init__.py) and [`__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/__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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__init__.py) and [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) for the package entry points, plus [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) for runtime configuration. The [`requirements.txt`](https://github.com/sansan0/TrendRadar/blob/main/requirements.txt) or [`pyproject.toml`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__init__.py) checks this environment variable and loads the specified configuration instead of the default [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) in the root directory.

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

The [`index.html`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/start-http.sh) script in the root launches a local server that serves [`index.html`](https://github.com/sansan0/TrendRadar/blob/main/index.html) by default.