High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
ALwrity is an AI-powered digital marketing platform designed to automate content strategy, creation, and performance optimization. The system follows a decoupled, full-stack architecture consisting of a FastAPI backend and a React frontend, supported by a modular service layer and a multi-provider AI integration engine.
Sources: README.md:1-20, SETUP_GUIDE.md:37-40
System Overview
The ALwrity platform is structured into three primary tiers: the Presentation Layer (Frontend), the Application Logic Layer (Backend), and the Data & Service Layer (AI and Database). This separation ensures scalability and allows the backend to serve multiple clients through a RESTful API.
The diagram above illustrates the request flow from the user interface through the backend orchestration services to external AI providers.
Sources: README.md:135-145, SETUP_GUIDE.md:42-88
Backend Architecture
The backend is built with FastAPI (Python 3.10+) and utilizes a modular service architecture. It manages authentication, data persistence via SQLAlchemy, and complex orchestration of AI prompts.
Core Backend Components
| Component | Description |
|---|---|
| FastAPI App | The entry point (app.py) defining routes, CORS middleware, and static file serving. |
| Modular Services | Domain-specific logic located in backend/services/ for SEO, Personas, and Calendar generation. |
| API Key Manager | Centralized security service for storing and validating multi-provider AI keys. |
| Prompt Orchestrator | A 12-step framework for chaining AI prompts to generate comprehensive content calendars. |
Sources: backend/README.md:15-60, backend/services/calendar_generation_datasource_framework/README.md:180-200
AI Orchestration and Chaining
A critical part of the architecture is the 12-Step Prompt Chaining Framework, which breaks down content generation into logical phases to maintain context and quality.
This flowchart represents the sequential data dependency within the AI content generation pipeline.
Sources: backend/services/calendar_generation_datasource_framework/README.md:215-235
Content Planning & Strategy Module
The Content Strategy module is the most complex component of the Application Logic layer. It utilizes over 30 strategic input fields to generate AI-powered recommendations.
Module Structure
- Core Orchestration: Manages the lifecycle of a content strategy.
- AI Analysis: Specialized services for Audience Intelligence, Competitive Intelligence, and Performance Optimization.
- Performance Layer: Implements a caching system (Redis-ready) with varied TTLs (e.g., 1 hour for AI analysis, 2 hours for strategies).
- Onboarding Integration: Automatically transforms initial website analysis into strategic fields.
Sources: backend/api/content_planning/services/content_strategy/README.md:8-40, backend/api/content_planning/services/content_strategy/IMPLEMENTATION_STATUS.md:15-40
Data & Persistence Layer
The platform uses a relational database model managed through SQLAlchemy. While SQLite is used for development and default setups, the architecture is designed to be PostgreSQL-ready for production environments.
Data Flow for Persistence
- API Requests: Capture user strategic inputs (Business objectives, target metrics).
- Service Processing: Business logic validates and cleans the data using
shared/utils. - ORM Layer: SQLAlchemy maps objects to tables such as
enhanced_writing_personasorenhanced_strategy_models. - AI Results: AI-generated analysis and content are stored back in the database for persistence and future "learning."
Sources: backend/README.md:120-130, backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:150-180
Technical Stack Summary
| Layer | Technologies |
|---|---|
| Frontend | React 18+, TypeScript, Material-UI, CopilotKit |
| Backend | FastAPI, Python 3.10+, Uvicorn |
| Database | SQLite (default), SQLAlchemy ORM (PostgreSQL ready) |
| AI Providers | OpenAI (GPT-4), Google (Gemini/Imagen), Anthropic (Claude), Mistral |
| Web Research | Tavily AI, Exa AI, Serper.dev |
| DevOps | Docker, Gunicorn, Python-dotenv |
Sources: README.md:105-120, SETUP_GUIDE.md:8-15
Conclusion
ALwrity's architecture emphasizes modularity and scalability. By isolating AI logic into a multi-step chaining framework and separating the frontend from the FastAPI backend, the system allows for continuous refinement of AI prompts and content strategies without impacting core platform stability. The planned evolution towards a shared "Modularity Plan" further organizes the code into core, module, and shared directories to support enterprise-level growth.
Sources: backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:20-50, README.md:160-170