Home

🎓 Optimal — Project Overview

🚀 Introduction

Optimal is a modern academic documentation platform designed to transform traditional course materials into a structured, interactive, and high-performance web experience.

Inspired by the clarity and usability of MDN Web Docs, Optimal replaces fragmented PDFs with a centralized, scalable system tailored for both students and educators.

It focuses on:

• 📖 Readable and structured content
• 🧭 Intuitive navigation
• ⚡ High performance with modern Angular
• 🌙 Accessibility through theming (dark/light mode)

---

🧱 Tech Stack

Optimal is built with a strong emphasis on performance, scalability, and developer experience.

Technology	Purpose
Angular 19	Core frontend framework
TypeScript 5	Type-safe application logic
Signals	Reactive state management
Marked	Markdown parsing engine
DOMPurify	HTML sanitization (security)
Bootstrap 5	Responsive UI and theming

---

🏗️ System Architecture

Optimal follows a feature-based scalable architecture, separating global concerns from domain-specific logic.

📂 Main Layers

src/app/
├── core/       # Global services (Markdown, ScrollSpy, Theme)
├── layout/     # Application shell (Header, Sidebar, Breadcrumbs)
├── shared/     # Reusable UI components
└── features/   # Business features (e.g., courses)

This structure ensures:

• clear separation of concerns
• scalability for future features
• maintainability across teams

---

🔗 Component Interaction

The UI is composed of structured components working together with core services.

🧩 Component Hierarchy

AppComponent
│
├── HeaderComponent        (theme, navigation)
├── SidebarComponent       (course navigation)
└── CourseDetailComponent
├── SectionComponent (renders Markdown)
└── TOC              (table of contents)

⚙️ Service Integration

• CourseService → loads course data
• MarkdownService → parses content
• ScrollSpyService → tracks active section
• ThemeService → manages UI theme

---

🔄 Data Flow — Markdown to Screen

Optimal treats Markdown as its primary data source.

📊 Content Pipeline

User Action (click course)
↓
Router (course id)
↓
CourseService (fetch Markdown)
↓
MarkdownService (parse → HTML)
↓
SectionComponent (render)
↓
ScrollSpyService (observe headings)
↓
TOC updates (active section)

This pipeline ensures:

• fast rendering
• dynamic navigation
• structured learning experience

---

🧩 Core Subsystems

1️⃣ Navigation & Layout

Managed by the layout/ layer:

• HeaderComponent
• SidebarComponent
• BreadcrumbComponent

Responsibilities:

• responsive layout
• navigation structure
• theme switching

---

2️⃣ Markdown Rendering Engine

Handled by MarkdownService:

• parses Markdown using Marked
• sanitizes output with DOMPurify
• generates heading anchors for navigation

---

3️⃣ Course Management

Courses are stored as a filesystem-based content system:

public/courses/
└── course-id/
├── index.json
├── introduction.md
└── ...

CourseService is responsible for:

• loading course files
• mapping routes → content
• caching and performance

---

🧭 Exploration Guide

To explore the project further, check these sections:

📘 Getting Started

• Setup instructions
• Development server
• Build & scripts

🗂 Project Structure

• Detailed explanation of folders
• Naming conventions
• Feature architecture

---

🎯 Vision

Optimal aims to evolve into a complete academic documentation ecosystem:

• structured course publishing
• collaborative content editing
• versioned documentation
• advanced search capabilities

---

🤝 Contribution

Contributions are welcome.

To get involved:

1. Fork the repository
2. Create a feature branch
3. Submit a Pull Request

---

📌 Final Note

Optimal is designed with scalability and clarity at its core.

It is not just a project — it is a foundation for building modern educational platforms.