Big-Link-Man/docs/architecture/components.md

System Components

The application will be structured into the following distinct modules within the source directory.

Core Modules

cli

Contains all Click command definitions. This is the user-facing entry point. It orchestrates calls to other modules but contains no business logic itself.

core

Handles application-wide concerns like configuration loading (master.json, .env), logging setup, and core application state.

database

Defines the SQLAlchemy models, repository interfaces (ABCs), and concrete repository implementations for SQLite. Manages the database session.

auth

Manages user authentication, password hashing, and role-based access control logic. Used by both the CLI and the API.

ingestion

Responsible for parsing the CORA .xlsx files and creating new Project entries in the database.

generation

Interacts with the AI service API (OpenRouter). Implements a simplified three-stage pipeline:

• AIClient: Handles OpenRouter API calls with retry logic
• PromptManager: Loads and formats prompt templates from JSON files
• ContentGenerator: Orchestrates title, outline, and content generation
• BatchProcessor: Processes job files and manages multi-tier batch generation
• JobConfig: Parses job configuration files with tier defaults

The generation module uses SEO data from the Project table (keyword, entities, related searches) to inform all stages of content generation. Validates word count and performs simple augmentation if content is below minimum threshold.

templating

Takes raw generated text and applies the appropriate HTML/CSS template based on the project's configuration.

interlinking

Contains the logic for generating the batch URL map and injecting the "wheel" of links into the generated HTML.

deployment

Implements the Strategy Pattern for multi-cloud deployments. Contains a base DeploymentStrategy and concrete classes for each provider (AWS S3, Azure Blob, etc.).

api

The FastAPI application. Defines API models (using Pydantic), routes, and dependencies. It will use the auth and database modules to service requests.