README.md

SecureLearning

Strengthening organizations through cybersecurity awareness.
Explore our site »

Table of Contents

1. About The Project
   • Built With
2. Architecture
3. Getting Started
   • Prerequisites
   • Environment Configuration
   • Development
4. Project Structure
5. CI/CD
6. Contributing
7. Contact

About The Project

SecureLearning is a cybersecurity awareness platform designed to strengthen organizational resilience by addressing the human element of security. It enables teams to run realistic, periodic phishing simulations and deliver targeted, just-in-time training based on real user behaviour.

The platform closes the loop between attack simulation, instant remediation, and measurable learning outcomes — giving security teams actionable insights into user susceptibility and improvement over time.

Key capabilities:

• Campaign Designer & Scheduler — Create, schedule, and manage phishing campaigns with configurable sending intervals and target user groups.
• Phishing Simulation Engine — Safely deliver simulated phishing emails via SMTP with pixel tracking for opens, clicks, and credential submissions.
• Content Management — Upload and organize training materials (documents, videos, markdown) with S3-compatible object storage.
• Learning Modules & Courses — Build structured training content with sections, quizzes, and progress tracking.
• Compliance Workflows — Enforce organizational compliance policies with quizzes and document acceptance tracking.
• Multi-tenant Architecture — Full tenant isolation through Keycloak realms with role-based access control (Admin, Org Manager, Content Manager).
• Audit-ready Dashboards — Real-time campaign statistics, user vulnerability scores, and repeat offender detection.
• Accessibility — Five theme modes including Deuteranopia, Protanopia, and Tritanopia support.

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                          Nginx (Reverse Proxy)                       │
│                    TLS termination · routing · static                 │
└──────────┬──────────────────────────────────┬────────────────────────┘
           │                                  │
    ┌──────▼──────┐                    ┌──────▼──────┐
    │  Frontend   │                    │   API       │
    │  React+Vite │                    │   FastAPI   │
    │  :5173      │                    │   :8000     │
    └─────────────┘                    └──────┬──────┘
                                              │
                    ┌─────────────┬────────────┼─────────────┬──────────────┐
                    │             │            │             │              │
             ┌──────▼─────┐ ┌────▼────┐ ┌─────▼─────┐ ┌────▼────┐  ┌─────▼─────┐
             │ PostgreSQL │ │ MongoDB │ │ Keycloak  │ │ Garage  │  │ RabbitMQ  │
             │  :5432     │ │  :27017 │ │   :8080   │ │  :3900  │  │  :5672    │
             └────────────┘ └─────────┘ └───────────┘ └─────────┘  └─────┬─────┘
                                                                         │
                                                                   ┌─────▼─────┐
                                                                   │   SMTP    │
                                                                   │  Worker   │
                                                                   └───────────┘

Service	Purpose
Frontend	React 19 SPA with TanStack Router, Tailwind CSS v4, shadcn/ui components, Keycloak SSO
API	FastAPI backend with SQLModel ORM, async MongoDB via Motor, S3 object storage
SMTP Worker	RabbitMQ consumer that sends phishing simulation emails via SMTP
PostgreSQL	Relational storage for campaigns, users, realms, sending profiles, compliance
MongoDB	Document storage for email templates, content pieces, modules, courses
Keycloak	Identity provider with multi-realm tenant isolation and RBAC
Garage	S3-compatible object storage for content files and tenant logos
RabbitMQ	Message broker for async email delivery and tracking event pipelines
Nginx	Reverse proxy with TLS, static asset serving, and route forwarding

(back to top)

Getting Started

Prerequisites

Tool	Version	Purpose
Docker	24+	Container runtime
Docker Compose	2.20+	Multi-service orchestration
Node.js	20+	Frontend development
uv	Latest	Python package manager
Python	3.12+	API and SMTP services

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Environment Configuration

1. Copy the example environment file for development:

   cp deployment/.env.dev.example deployment/.env

2. Review and adjust values in deployment/.env to match your local setup. Key settings include database credentials, Keycloak admin credentials, and RabbitMQ configuration.

Development

There are two ways to develop: fully containerized or local frontend + API with containerized infrastructure.

Option A — Fully Containerized (recommended for first run)

cd deployment
docker compose -f docker-compose.dev.yml up -d

This starts all services including the frontend dev server with hot reload at http://localhost:5173.

Option B — Local Frontend + API

1. Start infrastructure services only:

   cd deployment
   docker compose -f docker-compose.dev.yml up -d db mongo keycloak rabbitmq garage smtp

2. Start the frontend dev server:

   cd web
   npm install
   npm run dev

3. Start the API with hot reload:

   cd api
   uv sync --group dev
   uv run fastapi dev src/main.py

Default Ports

Service	URL
Frontend	http://localhost:5173
API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/api/docs
Keycloak Admin	http://localhost:8080
RabbitMQ Management	http://localhost:15672
Garage S3	http://localhost:3900

(back to top)

Project Structure

core/
├── api/                        # FastAPI backend
│   └── src/
│       ├── core/               # Settings, DB, security, object storage
│       ├── models/             # SQLModel tables + Pydantic schemas
│       ├── routers/            # API route handlers
│       ├── services/           # Business logic layer
│       ├── tasks/              # Background scheduler + tracking consumer
│       └── main.py             # App entry point
│
├── web/                        # React 19 SPA
│   └── src/
│       ├── components/         # UI components (ui/, shared/, feature dirs)
│       ├── routes/             # TanStack Router file-based routes
│       ├── services/           # API client functions per domain
│       ├── lib/                # Hooks, providers, utilities
│       └── main.tsx            # App entry point
│
├── smtp/                       # RabbitMQ email worker
│   └── src/
│       ├── core/               # RabbitMQ + API config
│       ├── emails/             # Email sender + template renderer
│       └── consumer.py         # Message consumer
│
├── deployment/                 # Docker Compose, Nginx configs, env templates
└── .github/workflows/          # CI/CD pipelines (per-service CI + CD)

(back to top)

CI/CD

The project uses GitHub Actions for continuous integration and deployment:

• CI (per-service): Triggered on pushes and PRs to dev with path filtering. Each service (API, Web, SMTP) runs its own pipeline: test/lint → SonarQube analysis → Docker image build and push to Docker Hub.
• CD: Triggered on release publish or manual dispatch. Runs on a self-hosted runner, generates TLS certificates, rebuilds, and redeploys the full stack using docker-compose.yml.

Docker images are published to Docker Hub with multi-stage builds (separate dev and prod targets).

(back to top)

Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Contact

Project Link: https://github.com/PEI-SecureLearning/core

(back to top)