Directory Structure & Organization
Relevant source files
The following files were used as context for generating this wiki page:
ALwrity follows a modular, decoupled architecture consisting of a FastAPI backend and a React frontend. The project is organized to separate core business logic, AI orchestration, and user interface components, while maintaining a clear path for migrating legacy scripts into the new modular framework.
The system is designed for high maintainability, utilizing a service-based architecture where specialized modules handle tasks like SEO analysis, content planning, and multi-provider AI integration.
Sources: README.md:65-72, SETUP_GUIDE.md:65-72
Core Project Layout
The root directory contains the primary application folders, startup scripts, and dependency definitions.
The high-level relationship between the backend, frontend, and legacy migration path.
Sources: SETUP_GUIDE.md:65-98, backend/README.md:14-27
Backend Architecture
The backend is a FastAPI application structured around the "API-Service-Model" pattern. This ensures that endpoint definitions, business logic, and data schemas are decoupled.
API Layer (backend/api/)
This directory contains modular endpoint definitions organized by feature. It serves as the entry point for frontend requests.
- content_planning/: Contains endpoints for strategy and calendar generation.
- onboarding.py: Manages user setup and provider configuration.
Sources: SETUP_GUIDE.md:68-80, backend/README.md:29-34
Service Layer (backend/services/)
The service layer implements the core business logic. It is increasingly modularized to prevent monolithic file growth.
- ai_service_manager.py: Orchestrates calls to various LLM providers (OpenAI, Gemini, Claude).
- seo_analyzer/: A specialized module for technical and content SEO audits.
- content_planning/: A new modular structure housing strategy, analytics, and recommendation modules.
| Module | Purpose | Key Components |
|---|---|---|
| SEO Analyzer | Technical & Content Audits | core.py, analyzers.py, utils.py |
| AI Manager | Provider Orchestration | ai_service_manager.py, llm_providers/ |
| Content Planning | Strategy & Scheduling | modules/, shared/, core/ |
Sources: backend/services/seo_analyzer/README.md:95-108, backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:65-115
Data Models (backend/models/)
Utilizes Pydantic and SQLAlchemy ORM to define data structures for API requests, responses, and database persistence.
- onboarding.py: Defines steps and status schemas.
- enhanced_strategy_models.py: Models for complex AI-generated marketing strategies.
Sources: SETUP_GUIDE.md:81-83, backend/README.md:52-56
Frontend Architecture
The frontend is a modern React 18+ application written in TypeScript, using Material-UI for components and CopilotKit for AI interactions.
Component Organization (frontend/src/components/)
Components are grouped by feature to allow for atomic development and testing.
- BlogWriter/: Advanced editor with AI sidebar and SEO panels.
- ContentPlanningDashboard/: Interface for generating AI content strategies.
- OnboardingWizard/: Multi-step setup process for new users.
State and Service Management
- stores/: Uses Zustand or similar for state management (e.g.,
enhancedStrategyStore.ts). - services/: Contains API clients (e.g.,
blogWriterApi.ts) that communicate with the FastAPI backend.
Sources: SETUP_GUIDE.md:88-105, README.md:73-77
Legacy & Migration Path (ToBeMigrated/)
This directory houses the original Streamlit-based tools and specialized AI writers. These are being systematically refactored into the modular backend/services/ structure.
The transition of standalone scripts into the integrated backend architecture.
Sources: ToBeMigrated/chatbot_custom/README.md:70-78, backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:120-135
Specialized Framework Structures
Calendar Generation Framework
Located in backend/services/calendar_generation_datasource_framework/, this module uses a registry-based pattern to handle evolving data sources.
| Component | Path | Description |
|---|---|---|
| Registry | registry.py | Central management for data sources. |
| Prompt Builder | prompt_builder.py | Strategy-aware prompt generation. |
| Data Sources | data_sources/ | Individual modules for keywords, pillars, and gaps. |
| Quality Gates | quality_gates/ | Validation modules for content uniqueness and mix. |
Sources: backend/services/calendar_generation_datasource_framework/README.md:19-38
Summary
ALwrity's directory structure is designed to support a transition from a collection of AI scripts to a comprehensive, enterprise-ready digital marketing platform. By organizing code into clearly defined API, Service, and Model layers in the backend, and feature-driven components in the frontend, the project maintains a high degree of scalability. The ToBeMigrated/ directory acts as a temporary workspace for legacy features, ensuring that new development remains clean and modular while legacy functionality is preserved.
Sources: backend/services/CONTENT_PLANNING_MODULARITY_PLAN.md:10-25, README.md:155-165