magma-you System Requirements Document

1. Introduction

The "magma-you" project is a Micro SaaS solution designed to assist regulated professionals in tracking their Continuing Education (CE) credits and license expirations. This document outlines the system requirements for the development of a production-ready Certificate/License Renewal Tracker, targeting individual licensed professionals and HR teams at firms employing many of them.

2. System Overview

The "magma-you" platform aims to provide a comprehensive solution for professionals who need to manage their licenses and certifications across various boards. The system will include features such as a beautiful landing page, user authentication, a dashboard, and AI capabilities for auto-classification of CE certificates and renewal deadline prediction. The platform will be designed with a modern aesthetic similar to Linear, Notion, or Vercel, ensuring a responsive and user-friendly experience.

3. Functional Requirements as Story Points

• As a User, I should be able to view a beautiful landing page that introduces the service.
• As a User, I should be able to register and log in using Google or Email.
• As a User, I should be able to manage my licenses and credentials through a dashboard.
• As a User, I should be able to receive reminders for upcoming license renewal deadlines.
• As a User, I should be able to store and manage my CE certificates.
• As a User, I should be able to subscribe to the service using Stripe for payments.
• As an Admin, I should be able to access an admin dashboard to manage users and subscriptions.
• As a User, I should be able to switch between light and dark mode for better accessibility.
• As a User, I should be able to update my user settings and billing information.
• As a User, I should be able to view analytics related to my license management.
• As a User, I should be able to experience seamless error handling and loading states.
• As a User, I should be able to benefit from AI features that auto-classify uploaded CE certificates against state requirements.
• As a User, I should be able to receive renewal deadline predictions powered by AI.

4. User Personas

• Individual Licensed Professional: A user who needs to track their own licenses and certifications.
• HR Team Member: A user responsible for managing licenses and certifications for a team of professionals.

5. Core User Flows

• User registers/logs in -> accesses dashboard -> uploads CE certificates -> receives auto-classification and deadline predictions -> manages licenses and credentials.
• Admin logs in -> accesses admin dashboard -> manages user accounts and subscriptions.

6. Visuals Colors and Theme

• primary: #1F2937 (dark slate)
• primary_light: #3E4C59 (lighter slate)
• secondary: #9CA3AF (cool gray)
• accent: #F59E0B (amber)
• highlight: #10B981 (emerald)
• bg: #F9FAFB (light gray)
• surface: #FFFFFF (white)
• text: #111827 (dark gray)
• text_muted: #6B7280 (muted gray)
• border: #D1D5DB (light gray)

7. Signature Design Concept

The landing page will feature an interactive timeline that visually represents the lifecycle of a professional license. Users can scroll horizontally through the timeline to see key milestones such as license acquisition, CE credits earned, and renewal deadlines. Each milestone will be represented by an icon that expands into a detailed view when clicked, providing users with insights and actions they can take. The timeline will be animated using motion/react to create a smooth and engaging experience.

Landing Hero Motion Brief

The hero section will depict a dynamic illustration of a professional's journey. Starting with a stack of documents (representing CE certificates), the documents will animate into a streamlined digital dashboard, symbolizing the transformation from manual tracking to automated management. The animation will loop every 10 seconds, with interactive elements allowing users to hover over documents to see details. The animation will be built using CSS and motion/react.

8. Interaction Model & Motion Direction

• Interaction Model: Animated
• The landing page will feature moderate scroll-triggered reveals and hover transitions. Interactive elements will have spring physics for a polished feel. Internal pages will maintain a static layout for clarity.

9. Non-Functional Requirements

• The system must be highly responsive and accessible across devices.
• The platform should support SEO best practices to enhance discoverability.
• The system must handle errors gracefully and provide informative feedback to users.
• The platform should ensure data security and privacy compliance.

10. Tech Stack

• Frontend: React for Web
• Backend: Python, FastAPI
• Database: MySQL or MariaDB, use alembic for migrations
• AI Models: GPT 5.4 for user-friendly response, Claude Sonnet 5 for academic or coding work
• AI Tools: Litellm for LLM Routing, Langchain
• Local Orchestration: Docker, docker-compose
• Server-side Orchestration: Kubernetes

11. Assumptions and Constraints

• The platform will initially target real estate agents as the primary user base.
• The system must integrate with Stripe for payment processing.
• The platform should be scalable to accommodate future growth and additional user segments.

12. Glossary

• CE: Continuing Education
• HR: Human Resources
• AI: Artificial Intelligence
• MVP: Minimum Viable Product
• SEO: Search Engine Optimization

This document outlines the comprehensive requirements for the "magma-you" project, ensuring a robust and user-friendly solution for managing professional licenses and certifications.