# mkmahmud/blog_ai_agent architecture

> Architecture diagram of the GitHub repository mkmahmud/blog_ai_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mkmahmud/blog_ai_agent
- Repository: https://github.com/mkmahmud/blog_ai_agent

## Overview

1. **Overall shape**
   - This is an **enterprise FastAPI backend** for AI-assisted blog generation.
   - The codebase is organized around **clean architecture boundaries**: API layer, application services, workflow/agents, persistence repositories, and infrastructure adapters.

2. **Primary request entrypoint**
   - `app/main.py` is the application bootstrap for FastAPI.
   - `app/api` contains the HTTP surface area: authentication, blog operations, and publishing endpoints, plus dependency wiring.
   - Request/response contracts are defined in `app/schemas`, keeping the API boundary separate from database models.

3. **Authentication and security boundary**
   - `app/services/auth_service.py` and `app/api/auth.py` implement user auth flows.
   - `app/core/security.py` indicates JWT-based security.
   - Cross-cutting controls also live in `app/core/rate_limit.py`, `app/core/cache.py`, `app/core/logging.py`, and `app/core/metrics.py`, suggesting the API is hardened for SaaS-style production use.

4. **Application/use-case layer**
   - `app/services` is the main orchestration layer for business operations:
     - blog creation and management,
     - publishing workflows,
     - auth-related use cases.
   - This layer mediates between API requests and the lower-level repositories/workflow engine, which is important for diagramming the boundary between transport and domain logic.

5. **Multi-agent content-generation pipeline**
   - The content workflow is modeled as a **LangGraph state machine** in `app/graphs/workflow.py` with state definitions in `app/graphs/state.py`.
   - The documented sequence is:
     - `START -> Planner -> Research -> SEO -> Writer -> Editor -> Fact Checker -> Publisher -> END`
   - Each stage is implemented as a separate agent in `app/agents`, with prompt templates stored in `prompts/`.
   - This is the core AI subsystem and should appear as a distinct pipeline in any architecture diagram.

6. **LLM/provider abstraction**
   - `app/llm/factory.py` centralizes model/provider selection.
   - The README says OpenAI is the default provider, with configuration switches for **AWS Bedrock**.
   - This means the agent workflow does not call providers directly; it goes through a model factory abstraction, which is a key boundary.

7. **Persistence layer**
   - `app/database` contains SQLAlchemy models, session setup, and Alembic metadata.
   - `app/repositories` is the persistence boundary, with separate repositories for blogs, users, and agent logs.
   - PostgreSQL is the primary relational datastore, and Alembic is used for schema migrations (`alembic/versions/...initial_schema.py`).

8. **Retrieval / knowledge layer**
   - `app/vectorstore/chroma.py` shows a **ChromaDB** integration for retrieval-augmented generation.
   - This likely supports research and fact-checking steps in the agent pipeline by storing and querying embeddings or reference content.
   - In diagrams, this should be shown as a separate data store from PostgreSQL, not as part of the transactional database.

9. **Async/background processing**
   - `app/queue/redis_queue.py` and `app/queue/jobs.py` indicate background job handling built on **Redis**.
   - This is likely used for long-running workflow steps or publishing tasks so the API can return quickly while work continues asynchronously.
   - Redis therefore serves two roles in the system: queue backend and supporting infrastructure for operational tasks.

10. **Publishing and output boundary**
   - `app/services/publishing_service.py` and `app/api/publish.py` handle the final handoff from generated content to publication.
   - The `Publisher` agent is the last stage in the workflow, which suggests publishing is treated as a distinct integration boundary rather than just another content transform.

11. **Configuration and environment management**
   - `app/core/config.py` centralizes environment-driven configuration.
   - The repo includes `.env.example`, Docker support, and separate deployment manifests, which indicates the runtime is designed to be configured via environment variables rather than hardcoded settings.

12. **Infrastructure and deployment**
   - Local development uses **Docker Compose** for PostgreSQL, Redis, and ChromaDB.
   - Deployment artifacts exist for **AWS ECS Fargate** and **Kubernetes** under `infrastructure/`.
   - The repo also includes explicit ECS task definitions for both the API and migration jobs, showing that migrations are treated as a separate deployable concern.

13. **Testing and validation**
   - `tests/test_workflow.py` exercises the multi-agent workflow.
   - `tests/test_security.py` covers security behavior.
   - This suggests the most important verification boundaries are workflow correctness and auth/security guarantees.

14. **What to emphasize in an architecture diagram**
   - Show the API as the entrypoint, services as orchestration, the LangGraph agent pipeline as the core AI engine, and the repositories as the persistence boundary.
   - Draw PostgreSQL, Redis, and ChromaDB as separate backing services.
   - Include LLM providers (OpenAI / Bedrock) as external dependencies behind the model factory.
   - Treat deployment/migrations as separate operational flows alongside the main API runtime.

Main entry points: [`app/api`](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/api) (API layer), [`app/graphs/workflow.py`](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/graphs/workflow.py) (Workflow), [`app/agents`](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/agents) (Agents), [`app/main.py`](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/main.py) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_interface["Interface"]
  node_n_main["App bootstrap<br/>FastAPI entrypoint<br/>[main.py]"]
  node_n_api["API layer<br/>HTTP routers"]
  node_n_schemas["Contracts<br/>Pydantic schemas"]
end

subgraph group_g_application["Application"]
  node_n_authsvc["Auth service<br/>use-case service<br/>[auth_service.py]"]
  node_n_blogsvc["Blog service<br/>use-case service<br/>[blog_service.py]"]
  node_n_pubsvc["Publish service<br/>integration service"]
  node_n_core["Runtime core<br/>cross-cutting"]
end

subgraph group_g_ai["AI Pipeline"]
  node_n_workflow["Workflow<br/>LangGraph state machine<br/>[workflow.py]"]
  node_n_state["Graph state<br/>workflow state<br/>[state.py]"]
  node_n_agents["Agents<br/>agent modules"]
  node_n_prompts["Prompts<br/>prompt templates"]
  node_n_llm["Model factory<br/>LLM abstraction<br/>[factory.py]"]
end

subgraph group_g_data["Data"]
  node_n_repos["Repositories<br/>persistence boundary"]
  node_n_db[("Postgres DB<br/>SQLAlchemy + Alembic")]
  node_n_vector[("ChromaDB<br/>retrieval store<br/>[chroma.py]")]
  node_n_queue["Redis queue<br/>background jobs"]
end

subgraph group_g_ops["Ops"]
  node_n_aws["AWS deploy<br/>ECS artifacts"]
  node_n_k8s["Kubernetes<br/>manifests"]
end

node_n_main -->|"serves"| node_n_api
node_n_main -->|"configures"| node_n_core
node_n_api -->|"uses"| node_n_schemas
node_n_api -->|"auth calls"| node_n_authsvc
node_n_api -->|"blog calls"| node_n_blogsvc
node_n_api -->|"publish calls"| node_n_pubsvc
node_n_authsvc -->|"reads/writes"| node_n_repos
node_n_blogsvc -->|"reads/writes"| node_n_repos
node_n_blogsvc -->|"starts"| node_n_workflow
node_n_pubsvc -->|"finalizes"| node_n_workflow
node_n_workflow -->|"transitions"| node_n_state
node_n_workflow -->|"executes"| node_n_agents
node_n_agents -->|"loads"| node_n_prompts
node_n_agents -->|"requests model"| node_n_llm
node_n_agents -->|"retrieves"| node_n_vector
node_n_repos -->|"stores"| node_n_db
node_n_queue -->|"runs jobs"| node_n_workflow
node_n_core -->|"guards"| node_n_api
node_n_aws -->|"deploys"| node_n_main
node_n_k8s -->|"deploys"| node_n_main

click node_n_main "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/main.py"
click node_n_api "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/api"
click node_n_schemas "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/schemas"
click node_n_authsvc "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/auth_service.py"
click node_n_blogsvc "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/blog_service.py"
click node_n_pubsvc "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/publishing_service.py"
click node_n_core "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/core"
click node_n_workflow "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/graphs/workflow.py"
click node_n_state "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/graphs/state.py"
click node_n_agents "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/agents"
click node_n_prompts "https://github.com/mkmahmud/blog_ai_agent/tree/main/prompts"
click node_n_llm "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/llm/factory.py"
click node_n_repos "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/repositories"
click node_n_db "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/database"
click node_n_vector "https://github.com/mkmahmud/blog_ai_agent/blob/main/app/vectorstore/chroma.py"
click node_n_queue "https://github.com/mkmahmud/blog_ai_agent/tree/main/app/queue"
click node_n_aws "https://github.com/mkmahmud/blog_ai_agent/tree/main/infrastructure/aws"
click node_n_k8s "https://github.com/mkmahmud/blog_ai_agent/tree/main/infrastructure/kubernetes"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_api,node_n_schemas toneBlue
class node_n_authsvc,node_n_blogsvc,node_n_pubsvc,node_n_core toneAmber
class node_n_workflow,node_n_state,node_n_agents,node_n_prompts,node_n_llm toneMint
class node_n_repos,node_n_db,node_n_vector,node_n_queue toneRose
class node_n_aws,node_n_k8s toneIndigo
```

## Components

### Interface

HTTP API and request/response boundary

- [App bootstrap](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/main.py): FastAPI entrypoint · Application startup and composition root · `app/main.py`
- [API layer](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/api): HTTP routers · Public endpoints for auth, blogs, and publishing · `app/api`
- [Contracts](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/schemas): Pydantic schemas · Request and response models at the API boundary · `app/schemas`

### Application

Business services and cross-cutting runtime controls

- [Auth service](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/auth_service.py): use-case service · Authentication and user access orchestration · `app/services/auth_service.py`
- [Blog service](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/blog_service.py): use-case service · Blog creation and management orchestration · `app/services/blog_service.py`
- [Publish service](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/services/publishing_service.py): integration service · Final handoff from generated content to publication · `app/services/publishing_service.py`
- [Runtime core](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/core): cross-cutting · Config, security, caching, logging, metrics, and rate limiting · `app/core`

### AI Pipeline

LangGraph workflow, agents, prompts, and model abstraction

- [Workflow](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/graphs/workflow.py): LangGraph state machine · Orchestrates the AI content-generation sequence · `app/graphs/workflow.py`
- [Graph state](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/graphs/state.py): workflow state · Shared state passed through the agent pipeline · `app/graphs/state.py`
- [Agents](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/agents): agent modules · Planner, research, SEO, writer, editor, fact-checker, and publisher agents · `app/agents`
- [Prompts](https://github.com/mkmahmud/blog_ai_agent/tree/main/prompts): prompt templates · Task-specific prompt content for each agent stage · `prompts`
- [Model factory](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/llm/factory.py): LLM abstraction · Selects and configures OpenAI or Bedrock backends · `app/llm/factory.py`

### Data

Transactional storage, retrieval, and background jobs

- [Repositories](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/repositories): persistence boundary · Blog, user, and agent-log data access layer · `app/repositories`
- [Postgres DB](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/database): SQLAlchemy + Alembic · Transactional relational storage and schema evolution · `app/database`
- [ChromaDB](https://github.com/mkmahmud/blog_ai_agent/blob/main/app/vectorstore/chroma.py): retrieval store · Vector retrieval for research and fact-checking support · `app/vectorstore/chroma.py`
- [Redis queue](https://github.com/mkmahmud/blog_ai_agent/tree/main/app/queue): background jobs · Async task dispatch and operational queue backend · `app/queue`

### Ops

Deployment and migration artifacts

- [AWS deploy](https://github.com/mkmahmud/blog_ai_agent/tree/main/infrastructure/aws): ECS artifacts · Production deployment and migration task definitions · `infrastructure/aws`
- [Kubernetes](https://github.com/mkmahmud/blog_ai_agent/tree/main/infrastructure/kubernetes): manifests · Cluster deployment, service, config, and secret manifests · `infrastructure/kubernetes`

## Connections

- App bootstrap → API layer: serves · Bootstraps the HTTP surface
- App bootstrap → Runtime core: configures · Loads runtime settings and cross-cutting controls
- API layer → Contracts: uses · Serializes and validates request/response contracts
- API layer → Auth service: auth calls · Routes authentication flows into the service layer
- API layer → Blog service: blog calls · Routes blog operations into the service layer
- API layer → Publish service: publish calls · Routes publishing requests into the service layer
- Auth service → Repositories: reads/writes · Persists and loads user/account data
- Blog service → Repositories: reads/writes · Persists and loads blog data
- Blog service → Workflow: starts · Triggers AI content generation workflow
- Publish service → Workflow: finalizes · Hands off generated content for publication
- Workflow → Graph state: transitions · Carries shared workflow state across stages
- Workflow → Agents: executes · Runs the planner/research/SEO/writer/editor/fact-checker/publisher stages
- Agents → Prompts: loads · Uses prompt templates per stage
- Agents → Model factory: requests model · Obtains provider-specific model clients through the factory
- Agents → ChromaDB: retrieves · Queries knowledge for research and verification
- Repositories → Postgres DB: stores · Persists through SQLAlchemy-backed relational storage
- Redis queue → Workflow: runs jobs · Supports asynchronous or long-running workflow execution
- Runtime core → API layer: guards · Applies security and operational controls to requests
- AWS deploy → App bootstrap: deploys · Production ECS runtime for the API and migrations
- Kubernetes → App bootstrap: deploys · Kubernetes runtime manifests for application components