SAM LMS - Smart African Learning Management System

A modern, feature-rich Learning Management System designed for African educational institutions, built with TypeScript, React, and cutting-edge authentication.

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0
PostgreSQL >= 14.0
Git for version control

Factory/Droid CLI Integration

SAM LMS includes full Factory/droid CLI integration for automated development workflows:

# Install Factory CLI globally
npm install -g @factory/cli

# Initialize project with droid automation
factory init sam-lms
factory droid setup

# Start automated development workflow
factory droid start

Installation

# Clone the repository
git clone https://github.com/Sudz/sam-lms.git
cd sam-lms

# Install dependencies (automated via droid)
npm run setup

# Configure environment
npm run env:setup

# Start development servers
npm run dev

📋 Available Scripts

Development

npm run setup          # Complete project setup with dependencies
npm run dev            # Start all development servers
npm run dev:backend    # Backend development server only
npm run dev:frontend   # Frontend development server only
npm run dev:db         # Database development tools

Testing

npm test               # Run all tests
npm run test:unit      # Unit tests only
npm run test:e2e       # End-to-end tests
npm run test:coverage  # Test coverage report
npm run test:watch     # Watch mode for development

Code Quality

npm run lint           # ESLint + Prettier
npm run lint:fix       # Auto-fix linting issues
npm run type-check     # TypeScript type checking
npm run format         # Format code with Prettier

Database

npm run db:migrate     # Run database migrations
npm run db:seed        # Seed database with sample data
npm run db:reset       # Reset database (dev only)
npm run db:studio      # Open database management studio

Deployment

npm run build          # Production build
npm run build:backend  # Backend production build
npm run build:frontend # Frontend production build
npm run deploy         # Deploy to production
npm run deploy:staging # Deploy to staging

Agent Automation

npm run agent:setup    # Setup agent automation
npm run agent:test     # Run automated tests via agents
npm run agent:deploy   # Automated deployment workflow
npm run agent:monitor  # Start monitoring agents

🏗️ Project Structure

sam-lms/
├── backend/                 # Node.js/TypeScript API server
│   ├── src/
│   │   ├── controllers/     # API route controllers
│   │   ├── middleware/      # Express middleware
│   │   ├── models/         # Database models
│   │   ├── routes/         # API routes
│   │   ├── services/       # Business logic
│   │   └── utils/          # Utility functions
│   ├── migrations/         # Database migrations
│   └── tests/             # Backend tests
├── frontend/               # React/TypeScript frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── pages/         # Page components
│   │   ├── services/      # API services
│   │   ├── stores/        # State management
│   │   └── utils/         # Frontend utilities
│   └── tests/             # Frontend tests
├── infrastructure/         # AWS/Terraform configs
├── docs/                   # Documentation
│   ├── agents.md          # Agent automation guide
│   ├── deployment-guide.md # Deployment instructions
│   └── aws-setup.md       # AWS configuration
├── .github/               # GitHub workflows
└── supabase/              # Database schemas

🔧 Environment Configuration

Environment Variables

Copy the example environment files and configure:

# Backend environment
cp backend/.env.example backend/.env

# Frontend environment  
cp frontend/.env.example frontend/.env

Required Environment Variables

Backend (.env)

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/sam_lms"

# Authentication
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3001"

# Payment Processing
PAYSTACK_SECRET_KEY="sk_test_your_paystack_secret"
PAYSTACK_PUBLIC_KEY="pk_test_your_paystack_public"

# SMS Services
AFRICAS_TALKING_USERNAME="your_username"
AFRICAS_TALKING_API_KEY="your_api_key"

# Email Services
RESEND_API_KEY="re_your_resend_api_key"

# AWS Configuration
AWS_ACCESS_KEY_ID="your_access_key"
AWS_SECRET_ACCESS_KEY="your_secret_key"
AWS_REGION="us-east-1"
AWS_S3_BUCKET="sam-lms-uploads"

# Factory/Droid Integration
FACTORY_API_KEY="your_factory_api_key"
DROID_AUTOMATION_TOKEN="your_droid_token"

API Key Management

Development Keys: Use test/sandbox keys for local development
Production Keys: Store in secure environment variables
Key Rotation: Regularly rotate API keys (monthly recommended)
Access Control: Limit API key permissions to minimum required

Secure Key Storage

# Using AWS Secrets Manager (production)
aws secretsmanager create-secret --name "sam-lms/production" --secret-string file://secrets.json

# Using environment-specific configs
npm run env:production  # Load production environment
npm run env:staging     # Load staging environment
npm run env:development # Load development environment

🤖 Agent Automation

SAM LMS includes comprehensive agent automation for development workflows. See docs/agents.md for detailed setup and configuration.

Quick Agent Setup

# Install agent dependencies
npm run agent:install

# Configure agent environment
npm run agent:configure

# Start automation agents
npm run agent:start

# Monitor agent activity
npm run agent:dashboard

🔄 CI/CD Pipeline

GitHub Actions Workflows

.github/workflows/ci.yml - Continuous Integration
.github/workflows/deploy.yml - Deployment pipeline
.github/workflows/test.yml - Automated testing
.github/workflows/security.yml - Security scanning

Pipeline Stages

Code Quality: ESLint, Prettier, TypeScript checks
Testing: Unit tests, integration tests, E2E tests
Security: Dependency scanning, SAST analysis
Build: Production builds for frontend and backend
Deploy: Automated deployment to staging/production

Deployment Environments

Development: Auto-deploy on feature branch push
Staging: Auto-deploy on main branch merge
Production: Manual approval required

🧪 Testing Strategy

Test Types

Unit Tests: Jest + Testing Library
Integration Tests: Supertest for API testing
E2E Tests: Playwright for browser automation
Performance Tests: Lighthouse CI

Running Tests

# Complete test suite
npm test

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:performance

# Test coverage
npm run test:coverage

📊 Monitoring & Analytics

Application Monitoring

Error Tracking: Sentry integration
Performance: New Relic APM
Uptime: Pingdom monitoring
Logs: CloudWatch Logs

Analytics Dashboard

# Start monitoring dashboard
npm run monitor:start

# View application metrics
npm run monitor:metrics

# Check system health
npm run monitor:health

🚀 Deployment

Production Deployment

# Build for production
npm run build

# Deploy to AWS
npm run deploy:production

# Verify deployment
npm run deploy:verify

Infrastructure as Code

Infrastructure is managed with Terraform:

# Initialize Terraform
cd infrastructure
terraform init

# Plan infrastructure changes
terraform plan

# Apply changes
terraform apply

🛡️ Security Features

Authentication: BetterAuth with multiple providers
Authorization: Role-based access control (RBAC)
Data Encryption: AES-256 encryption for sensitive data
API Security: Rate limiting, input validation, CORS
Security Headers: Helmet.js security headers
Vulnerability Scanning: Automated dependency checks

🌍 Localization

SAM LMS supports multiple African languages:

English (default)
Swahili
Amharic
Yoruba
Zulu

Translation files are located in frontend/src/locales/.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

TypeScript: Strict mode enabled
ESLint: Airbnb configuration
Prettier: Code formatting
Conventional Commits: Commit message format

📋 Issue Templates

When reporting bugs or requesting features, please use our issue templates:

Bug Report: .github/ISSUE_TEMPLATE/bug.yml
Feature Request: .github/ISSUE_TEMPLATE/feature_request.yml

🔒 Security

For security vulnerabilities, please review our Security Policy and report issues responsibly.

📜 License

Licensed under the ISC License. See LICENSE for details.

🙏 Acknowledgments

BetterAuth - Modern authentication for TypeScript
Paystack - African payment infrastructure
Africa's Talking - SMS and voice services
Resend - Email for developers
Amazon Web Services - Cloud infrastructure
Factory CLI - Development automation platform

💬 Support

Issues: Open a GitHub issue for bugs or feature requests
Documentation: Check the docs/ directory for detailed guides
Contact: Visit https://saml.co.za/ for more information
Community: Join our Discord server for discussions

🌟 Project Status

SAM LMS is under active development. Key features:

✅ BetterAuth integration (email/password, magic links)
✅ Paystack payment processing
✅ Africa's Talking SMS notifications
✅ Resend email integration
✅ PostgreSQL database with migrations
✅ React frontend with Vite
✅ Factory/droid CLI integration
✅ Automated testing suite
✅ CI/CD pipeline
🚧 Course management system
🚧 User dashboard and progress tracking
🚧 Advanced analytics and reporting
🚧 Mobile application

Built with passion for African learners — https://saml.co.za/

Name		Name	Last commit message	Last commit date
Latest commit History 95 Commits
.github		.github
backend		backend
curriculum		curriculum
docs		docs
frontend		frontend
infrastructure/database		infrastructure/database
supabase/migrations		supabase/migrations
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json

Uh oh!

License

Uh oh!

Sudz/sam-lms

Folders and files

Latest commit

History

Repository files navigation

SAM LMS - Smart African Learning Management System

🚀 Quick Start

Prerequisites

Factory/Droid CLI Integration

Installation

📋 Available Scripts

Development

Testing

Code Quality

Database

Deployment

Agent Automation

🏗️ Project Structure

🔧 Environment Configuration

Environment Variables

Required Environment Variables

Backend (.env)

API Key Management

Secure Key Storage

🤖 Agent Automation

Quick Agent Setup

🔄 CI/CD Pipeline

GitHub Actions Workflows

Pipeline Stages

Deployment Environments

🧪 Testing Strategy

Test Types

Running Tests

📊 Monitoring & Analytics

Application Monitoring

Analytics Dashboard

🚀 Deployment

Production Deployment

Infrastructure as Code

🛡️ Security Features

🌍 Localization

🤝 Contributing

Development Workflow

Code Standards

📋 Issue Templates

🔒 Security

📜 License

🙏 Acknowledgments

💬 Support

🌟 Project Status

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages