System Requirements Document (SRD)

Project Name: magma-earth

1. Introduction

magma-earth is a creative and interactive project inspired by Moham's heartfelt dialogue between a child and Earth. The project aims to foster awareness about global issues such as war, poverty, and environmental degradation while promoting hope, peace, and faith. This document outlines the system requirements for the development of the magma-earth platform, which will serve as a digital space for storytelling, education, and engagement.

The platform will be designed with a focus on users in Jordan and neighboring countries, ensuring cultural relevance and accessibility. It will incorporate themes of innocence, resilience, and faith, as reflected in the original dialogue.

2. System Overview

magma-earth will be a web-based platform with optional mobile app integration. It will feature interactive storytelling, educational resources, and community engagement tools. The system will allow users to explore narratives, contribute their own stories, and learn about global challenges and solutions.

Key features include:

• A visually captivating homepage inspired by the dialogue's themes.
• Interactive storytelling modules.
• Educational content on environmental and humanitarian issues.
• Community forums for sharing ideas and discussions.
• Integration of faith-based messages to inspire hope and resilience.

The platform will be accessible in Arabic and English, with a user-friendly interface tailored to the cultural and linguistic needs of users in Jordan and the surrounding region.

3. Functional Requirements

• As a User, I should be able to read interactive stories inspired by the dialogue.
• As a User, I should be able to contribute my own stories and ideas to the platform.
• As a User, I should be able to access educational resources about global issues such as war, poverty, and environmental degradation.
• As a User, I should be able to participate in community discussions and forums.
• As an Admin, I should be able to moderate user content and ensure compliance with community guidelines.
• As an Admin, I should be able to manage educational content and storytelling modules.
• As a Guest, I should be able to explore the platform and read stories without creating an account.

4. User Personas

User

• Description: Individuals interested in storytelling, education, and global issues.
• Goals: To read, learn, and contribute to the platform.
• Skills: Basic digital literacy.

Admin

• Description: Moderators and content managers responsible for maintaining the platform.
• Goals: To ensure the platform runs smoothly and adheres to guidelines.
• Skills: Advanced digital literacy and content management expertise.

Guest

• Description: Casual visitors exploring the platform without registering.
• Goals: To browse stories and learn about the platform's purpose.
• Skills: Basic digital literacy.

5. Visuals Colors and Theme

Color Palette

The color palette for magma-earth is designed to evoke emotions of hope, resilience, and connection to nature.

• Background: #F5F3E7 (Soft Sand Beige)
• Surface: #E8D9B8 (Warm Earthy Gold)
• Text: #3B2F2F (Deep Charcoal Brown)
• Accent: #FF6F61 (Vivid Coral Red)
• Muted Tones: #B8C2A8 (Calm Olive Green)

6. Signature Design Concept

Interactive Storybook Homepage

The homepage will resemble an open storybook, with pages that "turn" as users scroll or swipe. Each page will feature animated illustrations inspired by the dialogue, such as a crying Earth and a comforting child.

• Animations:

  • The Earth will subtly "cry" with animated tears that shimmer and fade.
  • The child will offer a glowing light that spreads across the page, symbolizing hope.

• Transitions:

  • Pages will flip with a smooth, tactile animation, mimicking the feel of a real book.
  • As users navigate, the background will shift from dark tones (representing hardship) to lighter tones (representing ease and hope).

• Micro-interactions:

  • Hovering over text will reveal translations or additional context.
  • Clicking on illustrations will trigger short animations or sound effects, such as the Earth sighing or the child laughing.

This design concept will make the platform instantly memorable and emotionally engaging, drawing users into the narrative while providing an intuitive and delightful user experience.

7. Non-Functional Requirements

• The platform must support Arabic and English languages.
• The system should be optimized for low-bandwidth environments to ensure accessibility in regions with limited internet connectivity.
• The platform must comply with data privacy regulations in Jordan and neighboring countries.
• The system should be scalable to accommodate increasing user traffic.

8. Tech Stack

Frontend

• React for Web
• React Native for Mobile App

Backend

• Python
• FastAPI

Database

• MySQL or MariaDB (using Alembic for migrations)

AI Models

• GPT 5.2 for user-friendly responses
• Claude 4.5 Opas for academic or coding work
• Google Nano Banana for image generation

AI Tools

• Litellm for LLM Routing
• Langchain

Local Orchestration

• Docker
• docker-compose

Server-Side Orchestration

• Kubernetes

9. Assumptions and Constraints

• The platform will primarily target users in Jordan and neighboring countries.
• The system will be designed to accommodate cultural and linguistic preferences specific to the region.
• Budget constraints may limit the scope of advanced features in the initial release.
• The platform will rely on cloud hosting services for scalability and reliability.

10. Glossary

• Interactive Storybook: A digital storytelling format that mimics the experience of reading a physical book, enhanced with animations and interactivity.
• LLM Routing: A method for directing queries to the most appropriate large language model based on context.
• Alembic: A database migration tool for Python applications.
• Docker: A platform for developing, shipping, and running applications in containers.
• Kubernetes: An open-source system for automating deployment, scaling, and management of containerized applications.

This document provides a comprehensive overview of the requirements for the magma-earth project, ensuring alignment with Moham's vision and the project's goals.