mkmahmud/blog_ai_agent

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.