Backend Service Design
Relevant source files
The following files were used as context for generating this wiki page:
- backend/README.md
- SETUP_GUIDE.md
- backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md
- backend/api/content_planning/services/content_strategy/README.md
- backend/api/content_planning/services/content_strategy/IMPLEMENTATION_STATUS.md
- backend/services/blog_writer/README.md
- backend/services/seo_analyzer/README.md
The ALwrity backend is a high-performance, modular system built using the FastAPI framework. It is designed to provide robust AI-powered digital marketing capabilities, including content strategy generation, SEO analysis, and automated content writing. The architecture prioritizes separation of concerns, scalability, and seamless integration with multiple AI providers such as OpenAI, Google Gemini, and Anthropic.
Sources: backend/README.md:1-15, README.md:25-35, SETUP_GUIDE.md:31-70
Core Architectural Patterns
ALwrity employs a modular service-oriented architecture. The backend is structured into distinct layers: the API layer for endpoint definitions, the Service layer for business logic orchestration, and the Model layer for data structures.
The diagram illustrates the flow from client requests through the FastAPI application layer to modular business services and external integrations.
Sources: backend/README.md:24-45, backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:19-45
Base Content Service Pattern
A standardized BaseContentService abstract class is utilized across modules to ensure consistent initialization, input validation, and processing logic. This pattern supports maintainability and standardizes error handling.
| Component | Responsibility |
|---|---|
initialize() | Sets up service dependencies and database sessions. |
validate_input() | Ensures incoming data meets specific module requirements. |
process() | Executes the main business logic of the service. |
Sources: backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:73-95
Content Planning & Strategy System
The Content Strategy module is the most complex component of the backend, involving a 12-step automated generation process. It utilizes 30+ strategic input fields to generate AI-powered recommendations.
Flow of the content strategy generation process highlighting modular sub-services.
Implementation Modules
- Core Orchestration: Manages the flow via
EnhancedStrategyService. - AI Analysis: Handles comprehensive analysis including audience and competitive intelligence.
- Onboarding Integration: Auto-populates strategy fields from website analysis and user preferences.
- Performance & Caching: Implements intelligent caching (TTL ranges from 30 mins to 2 hours) for AI analysis results.
Sources: backend/api/content_planning/services/content_strategy/README.md:5-40, backend/api/content_planning/services/content_strategy/IMPLEMENTATION_STATUS.md:12-40
SEO and Content Analysis Services
The SEO Analyzer is a modular system that provides technical, content, and performance insights through a progressive analysis pipeline.
Progressive Analysis Pipeline
- Fast Analysis: Checks URL structure, meta tags, and accessibility.
- Technical SEO: Evaluates sitemaps, robots.txt, and canonical URLs.
- Slow Analysis: Measures performance metrics and security headers with graceful timeouts.
| Analyzer Type | Focus Areas |
|---|---|
ContentAnalyzer | Heading hierarchy (H1-H3), word count (min 300), alt text. |
MetaDataAnalyzer | Title length (30-60 chars), Meta description (70-160 chars). |
PerformanceAnalyzer | Page load speed, GZIP compression, and caching headers. |
Sources: backend/services/seo_analyzer/README.md:7-40, backend/services/seo_analyzer/README.md:130-150
AI Writer & Research Architecture
The AI Blog Writer service is refactored into a specialized research and outline generation framework.
Sequence of blog creation from initial research to SEO-optimized outline.
- Research Module: Combines keyword analysis, competitor intelligence, and content angle discovery using Google Search grounding.
- Outline Module: Manages the generation and optimization of article structures, ensuring they follow SEO best practices.
Sources: backend/services/blog_writer/README.md:15-45
Database & Model Design
The backend utilizes SQLAlchemy ORM for database operations, supporting SQLite for development and PostgreSQL for production environments.
Key Data Models
- WritingPersona: Stores 20+ linguistic metrics, brand voice, and stylistic fingerprints.
- EnhancedStrategy: Captures business objectives, target metrics, and content pillars.
- SEOAnalysisResult: Stores scores, health status, and categorized issues (Critical, Warning, Recommendation).
Sources: backend/services/persona/TBD_persona_enhancements.md:20-40, backend/services/seo_analyzer/README.md:75-90, SETUP_GUIDE.md:138-145
System Monitoring & Reliability
The backend includes comprehensive health monitoring and a standardized logging middleware to track service performance and AI interaction quality.
- Health Checks: Available at
/health, verifying database connectivity and service status. - AI Quality Gates: Threshold-based validation (e.g., quality scores ≥0.8) ensures AI outputs meet strategic standards before being served.
- Timeout Management: Robust handling for network-intensive operations like web crawling and AI generation.
Sources: backend/README.md:118-125, backend/services/calendar_generation_datasource_framework/test_12_step_calendar_generation.md:154-175, backend/services/seo_analyzer/README.md:155-165
Conclusion
The Backend Service Design of ALwrity is built on a modular, extensible foundation that leverages FastAPI's speed and Python's rich AI ecosystem. By separating concerns into distinct research, strategy, and content modules, the system remains maintainable even as it integrates complex 12-step AI workflows. This design ensures that solopreneurs can access enterprise-level marketing intelligence through a stable and scalable architecture.