Data Flow

Core Component Relationships

The interconnections between core components are critical for understanding the system's architecture:

App.js as the Central Orchestrator

App.js serves as the central orchestration component in Aether CMS. It:

1. Initializes all core systems in the proper sequence
2. Connects the Routes and Hook System
3. Sets up all API endpoints
4. Creates middleware for security and authentication
5. Manages error handling for the entire application

// From app.js
export async function setupApp(app, config) {
    // Initialize core systems
    hookSystem = new HookSystem()
    fileStorage = new FileStorage(config.uploadsDir)
    authManager = new AuthManager(config.dataDir)
    // ...

    // Set up API routes
    setupContentApi(app, systems)
    setupThemeApi(app, systems)
    setupMediaApi(app, systems)
    setupUserApi(app, systems)
    setupStaticApi(app, systems)
}

Hook System Integration

The Hook System provides extension points throughout the application:

1. It's initialized early in the bootstrap process
2. Routes utilize hooks for request processing
3. Content rendering passes through hooks for modification
4. APIs apply hooks for filtering and transformation
5. Static site generation uses hooks for content optimization

// Example of hook usage in content API
const filteredPosts = hookSystem.applyFilters("api_posts", posts, req)

Routes and Request Flow

Routes define how requests flow through the system:

1. Client requests enter through the Routes component
2. Routes use the Hook System for processing
3. App.js connects Routes to the appropriate API endpoints
4. APIs interact with the necessary Service Layer components
5. Responses flow back through the same path# Aether CMS Data Flow Documentation

Overview

Aether CMS is built with a modular architecture that efficiently manages data flow between its various components. This document provides a comprehensive overview of how data moves through the system, from user input to storage and output generation. Understanding these data flows is crucial for developers who want to extend or customize Aether CMS functionality.

System Architecture

Aether CMS follows a layered architecture with clear separation of concerns:

1. Client Layer

The entry point for all interactions with the system. This includes:

• Admin Interface - Where content management occurs
• Frontend Theme - What visitors see when browsing the site
• Static Site Generator - Creates static HTML files for deployment

2. Core App Layer

The orchestration layer that initializes and coordinates all subsystems:

• App.js - The central component that initializes all subsystems and connects them
• Routes - Handles URL routing for both frontend and admin interfaces
• Hook System - Provides plugin-like extensibility for the CMS

The Core App Layer has an important internal flow:

• Hook System provides services to Routes
• Routes are integrated into App.js
• App.js connects to all API endpoints

3. API Layer

RESTful endpoints that handle specific types of requests:

• Content API - Manages posts, pages, and custom content
• Media API - Handles file uploads and media management
• Theme API - Controls theme selection and customization
• User API - Manages authentication and user permissions
• Static API - Facilitates static site generation

4. Service Layer

Specialized managers that implement the business logic:

• Content Manager - Handles content creation, storage, and retrieval
• Theme Manager - Manages theme templates and appearance
• Auth Manager - Controls authentication and permissions
• File Storage - Manages media uploads and file operations
• Settings Service - Stores and retrieves configuration options

5. Data Storage Layer

Persistent storage for content, settings, and files:

• Content Files - Markdown files with YAML frontmatter
• Theme Files - HTML templates, CSS, and JavaScript files
• Users & Sessions - Authentication and session data
• Uploaded Files - Images and other media
• Settings Files - System and site configuration

6. Output Layer

Generated static site files for deployment:

• HTML, CSS, JavaScript, and assets compiled for distribution

Key Data Flows

Content Management Flow

The core functionality of Aether CMS is content management. Here's how content data flows through the system:

Content Creation

Admin Interface → App.js → Content API → Content Manager → Content Files

1. User Input: The admin interface collects post/page data through the editor.
2. Request Routing: App.js directs the request to the Content API.
3. API Processing: The Content API validates the request and passes it to ContentItemManager.
4. Content Processing:
   • The ContentItemManager generates an ID and adds timestamps.
   • For posts, it processes frontmatter properties like category and tags.
   • For pages, it handles pageType and parent relationships.
5. Storage: Content is saved as Markdown files with YAML frontmatter.

Content Retrieval

Frontend Request → Routes → Hook System → App.js → Content API → ContentQueryManager → Content Files → Template Rendering

1. URL Request: User visits a content URL (e.g., /post/my-post).
2. Route Handling: Routes identify the content type and slug, passing through the Hook System.
3. Request Processing: App.js directs the request to the Content API.
4. Content Query: ContentQueryManager retrieves the content by property (e.g., slug).
5. Content Processing:
   • Content is parsed from Markdown to HTML.
   • Related content (prev/next posts, category listings) is fetched if needed.
   • Hook system filters may modify the content.
6. Template Rendering: The content is passed to the theme template for rendering.

Theme System Flow

The theme system determines how content is presented to users:

Frontend Request → Routes → Hook System → App.js → Theme API → ThemeManager → Template Rendering

1. Request Handling: A frontend request is received by Routes, processed through the Hook System.
2. API Routing: App.js directs the request to the Theme API.
3. Theme Discovery: During initialization, the system scans for available themes.
4. Theme Selection: The active theme is determined from settings.
5. Template Resolution: When rendering content, the appropriate template is selected following the resolution path:
   • For posts: custom/<slug>.html → post.html → content.html → layout.html
   • For pages: custom/<slug>.html → page.html → content.html → layout.html
   • For taxonomies: custom/<taxonomy>-<term>.html → custom/<taxonomy>.html → taxonomy.html → layout.html
6. Template Data Preparation: Template data is assembled, including:
   • Content data (title, body, metadata)
   • Site settings
   • Navigation menus
   • Administrative bars (for logged-in users)
7. Hook Processing: Template data passes through the hook system, allowing for customizations.
8. HTML Rendering: The template is rendered with the prepared data.

File Storage Flow

Media files (images and documents) are managed through a dedicated subsystem:

Media Upload → App.js → Media API → FileManager → ImageHandler/DocumentHandler → File System

1. File Upload: Files are uploaded via the admin interface.
2. Request Routing: App.js directs the request to the Media API.
3. File Processing:
   • A unique filename is generated based on the original name and a random ID.
   • Images may be processed for thumbnails or optimizations.
   • Metadata is extracted (dimensions, file type, etc.).
4. Storage: Files are saved to the appropriate directory (images or documents).
5. Metadata Storage: A separate metadata JSON file is created alongside the media file.
6. Reference Tracking: When media is embedded in content, references are tracked to maintain integrity.

Authentication Flow

User authentication follows a secure process:

Login Request → Routes → App.js → Auth API → UserManager → PasswordService → Session Creation

1. Login Attempt: User submits credentials to the login form.
2. Request Routing: Routes direct the request to App.js, which forwards it to the Auth API.
3. Rate Limiting: RateLimiter checks for excessive login attempts.
4. User Lookup: UserManager retrieves the user by username.
5. Password Verification: PasswordService verifies the password hash using Argon2.
6. Session Creation: Upon successful authentication, SessionManager creates a token.
7. Cookie Storage: The token is stored as a secure HTTP-only cookie.
8. Authorization: For subsequent requests, middleware extracts and verifies the token.

Static Site Generation Flow

Aether CMS can generate static sites for deployment:

Static Site Gen → Hook System → Routes → App.js → Static API → Service Layer → Data Storage → Static Output

1. Generation Trigger: Admin initiates generation via UI or command line.
2. Process Orchestration:
   • Request flows through the Hook System and Routes
   • App.js directs the request to the Static API
   • Static API accesses multiple services simultaneously:
     • Content Manager for all published content
     • Theme Manager for rendering templates
     • Auth Manager for permission validation
     • File Storage for media assets
     • Settings Service for configuration options
3. Content Collection: The generator fetches all published content.
4. Template Processing: Each content item is processed with its appropriate template.
5. Asset Collection: Theme assets and uploaded media are copied to the output directory.
6. SEO File Generation: Sitemap XML, RSS feed, and robots.txt are generated.
7. URL Processing: URLs are formatted according to the configured pattern (clean or with extensions).
8. File Output: All generated files are written to the specified output directory.

Data Storage

Aether CMS uses file-based storage for all data:

Content Storage

Content is stored as Markdown files with YAML frontmatter:

---
id: "1684319454298"
title: "Sample Post"
slug: "sample-post"
status: "published"
author: "admin"
createdAt: "2023-05-17T10:30:54.298Z"
updatedAt: "2023-05-17T11:45:12.456Z"
category: "development"
tags: ["javascript", "cms", "tutorial"]
---

# This is a sample post

Content goes here in Markdown format.

## Subheading

More content...

User Data

User accounts are stored in JSON format:

[
    {
        "id": "a1b2c3d4",
        "username": "admin",
        "email": "admin@example.com",
        "passwordHash": "$argon2id$v=19$m=65536,t=3,p=2$...",
        "role": "admin",
        "createdAt": "2023-05-01T00:00:00.000Z",
        "updatedAt": "2023-05-01T00:00:00.000Z"
    }
]

Settings

Settings are stored in a central JSON file:

{
    "siteTitle": "My Aether Site",
    "siteDescription": "A site built with Aether",
    "postsPerPage": 10,
    "activeTheme": "default",
    "siteUrl": "https://example.com",
    "staticOutputDir": "_site",
    "staticCleanUrls": true
}

Media Files

Media files are stored with accompanying metadata:

/content/uploads/images/my-image-a1b2c3d4.jpg
/content/uploads/images/my-image-a1b2c3d4.jpg.metadata.json

{
    "alt": "Sample image",
    "width": 800,
    "height": 600,
    "createdAt": "2023-05-17T10:30:54.298Z",
    "updatedAt": "2023-05-17T10:30:54.298Z"
}

Hooks and Extensions

The Hook System provides a way to modify data as it flows through the system:

Action Hooks

Triggered at specific points but don't modify data:

hookSystem.doAction("post_created", post)

Filter Hooks

Allow modification of data as it passes through:

const filteredPosts = hookSystem.applyFilters("api_posts", posts, req)

Performance Considerations

Aether CMS optimizes data flow for performance:

1. In-Memory Caching: Settings and frequently accessed data are cached in memory.
2. Lazy Loading: Content is loaded only when needed.
3. Pagination: Large collections are paginated to reduce memory usage.
4. Query Parameters: Content can be optimized with parameters:
   • frontmatterOnly=true - Returns only metadata without content
   • properties=id,title,slug - Returns only specified properties
   • summaryView=true - Returns truncated content previews
5. Batch Processing: Bulk operations use batching to manage memory usage.

Security in Data Flow

Aether CMS implements several security measures:

1. Input Validation: All user inputs are validated at the API layer.
2. Password Security: Passwords are hashed using Argon2id with secure parameters.
3. Rate Limiting: Login attempts are rate-limited to prevent brute force attacks.
4. Token-Based Authentication: Secure HTTP-only cookies for authentication.
5. Permission Checks: Role-based access control for administrative operations.
6. Data Sanitization: Content is sanitized before storage and rendering.

Troubleshooting Common Data Flow Issues

Content Not Appearing

1. Check the content status (must be "published").
2. Verify the slug is properly formatted.
3. Check template path resolution.
4. Look for hook filters that might be affecting content display.

Theme Changes Not Reflected

1. Verify the active theme in settings.
2. Check template path resolution.
3. Clear the theme cache using the refresh endpoint.

Media Reference Issues

1. Check for correct URL references in content.
2. Verify that the media file exists.
3. Check media metadata for problems.
4. Use the reference manager to identify and fix broken references.

Advanced Data Flow Customization

Custom Content Types

You can extend Aether CMS with custom content types by:

1. Creating a new directory under /content/data/.
2. Implementing a custom ContentTypeManager.
3. Adding API endpoints for the new type.
4. Adding routes for frontend display.

Custom Data Storage

While Aether CMS uses file-based storage by default, you can implement custom storage:

1. Create adapter classes that implement the same interfaces.
2. Replace the default managers during initialization.
3. Implement custom read/write methods.

Conclusion

The data flow in Aether CMS is designed to be modular, extensible, and performant. By understanding how data moves through the system, developers can effectively customize and extend the CMS to meet specific requirements while maintaining the integrity of the core architecture.

For further details on specific components, refer to the API documentation and the code comments in the relevant modules.