Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
692 lines (495 loc) · 10.4 KB

ARCHITECTURE.md

File metadata and controls

692 lines (495 loc) · 10.4 KB
Raw

ARCHITECTURE — Learn With Linga (Engineering Insights Platform)

1. Overview

Learn With Linga — Engineering Insights is a markdown-driven engineering insight platform.

The system is designed to:

  • separate content from rendering
  • preserve engineering understanding
  • reduce UI duplication
  • support scalable insight organization
  • maintain a structured reading experience

The architecture prioritizes:

simplicity, maintainability, and insight-focused rendering

2. Core Architectural Philosophy

The platform follows a core principle:

Write structured markdown once → render dynamically everywhere

This removes the need for:

  • manual page creation
  • hardcoded UI per insight
  • repeated rendering logic

The architecture intentionally separates:

Layer Responsibility
Content Engineering insights
API Content transformation
Frontend Rendering + UX
Styling Reading experience

3. High-Level System Architecture

The platform consists of four major layers.

1. Content Layer

Location:

client/public/insights/

Purpose:

  • stores markdown insight files
  • organizes insights by engineering domain
  • acts as the source of truth

Structure:

Content Layer Structure

client/public/insights/
│
├── frontend/
│   ├── README.md
│   └── insights/
│
├── backend/
│   ├── README.md
│   └── insights/
│
├── cloud/
│   ├── README.md
│   └── insights/
│
├── cloud-concepts/
│   ├── README.md
│   └── insights/
│
├── dsa/
│   ├── README.md
│   └── insights/
│
├── projects/
│   ├── README.md
│   └── insights/
│
├── failures-and-fixes/
│   ├── README.md
│   └── insights/
│
├── professional-communication/
│   ├── README.md
│   └── insights/
│
├── dbms/
│   ├── README.md
│   └── insights/
│
├── nosql/
│   ├── README.md
│   └── insights/
│
├── reasons-behind-thoughts/
│   ├── README.md
│   └── insights/
│
├── ai-and-ml/
│   ├── README.md
│   └── insights/
│
└── meta-learning/
    ├── README.md
    └── insights/

Each domain contains:

insights/
  ├── *.md

2. API Layer (Serverless)

Location:

api/insights/[domain].js

Purpose:

  • dynamically reads markdown files
  • converts filesystem data into structured JSON
  • provides domain-based insight APIs

The API acts as a transformation layer between:

  • filesystem content
  • frontend rendering

Core API Flow

The serverless function:

  1. receives domain from route params
  2. resolves insight directory path
  3. reads markdown files
  4. sorts files chronologically
  5. converts file content into JSON
  6. returns structured response

Filesystem Resolution

const dirPath = path.join(
  process.cwd(),
  "client",
  "public",
  "insights",
  domain,
  "insights"
);

This ensures:

  • environment-independent resolution
  • stable deployment behavior
  • compatibility with serverless runtime

API Response Structure

[
  {
    "title": "file-name",
    "category": "domain",
    "content": "markdown content"
  }
]

3. Frontend Layer (React)

Frontend responsibilities:

  • domain exploration
  • insight listing
  • markdown rendering
  • reading flow management
  • navigation hierarchy
  • responsive UX
  • animated section rendering

Routing Architecture

Routes:

/
/domains
/domain/:name
/domain/:name/insights
/why-this-exists
/how-to-use-insights

Navigation Hierarchy

The system intentionally follows a layered navigation structure:

Home
  ↓
Domains
  ↓
Domain
  ↓
Insights
  ↓
Insight Detail View

This reduces:

  • navigation overload
  • cognitive clutter
  • mixed content presentation

4. Styling & UX Layer

Purpose:

  • preserve reading clarity
  • maintain structured hierarchy
  • improve long-form readability

The styling system controls:

  • card layouts
  • spacing consistency
  • responsive rendering
  • CTA hierarchy
  • animated reveals
  • image presentation
  • reading flow

4. Rendering Pipeline

The rendering pipeline follows:

Markdown File
    ↓
Serverless API
    ↓
JSON Response
    ↓
React Fetch
    ↓
ReactMarkdown Rendering
    ↓
Styled Insight UI

5. Markdown Rendering System

The platform uses:

ReactMarkdown

to preserve:

  • formatting
  • headings
  • images
  • lists
  • blockquotes

without destructive parsing.

Section-Based Rendering

Insights are split using:

split(/(?=\n## )/g)

Purpose:

  • preserve markdown structure
  • enable section animations
  • support card-based rendering

Each section becomes:

Section → Card → Animated Render Block

6. Image Rendering Architecture

Images are stored in:

client/public/images/

Referenced inside markdown as:

/images/...

Learning Evidence Images

The platform supports proof-backed learning through dedicated image storage.

Location:

client/public/images/images-from-learning/

Purpose:

  • debugging evidence
  • implementation screenshots
  • learning proof
  • system observations
  • before/after comparisons

These images act as supporting evidence for engineering insights rather than decorative assets.

This enables:

Learning
   ↓
Observation
   ↓
Evidence
   ↓
Insight

The image layer strengthens insight quality by connecting explanations with verifiable learning artifacts.

Rendering Strategy

Images:

  • render inside insight cards
  • follow controlled sizing
  • support responsive scaling
  • maintain edge-aligned layout

CSS controls:

  • rendering width
  • scaling behavior
  • hover interaction
  • overflow protection

7. Domain Architecture

Domains separate different engineering understanding layers.

The platform intentionally distinguishes between:

  • domain-specific knowledge
  • cross-domain insights
  • engineering reflections
  • debugging-driven lessons

This prevents unrelated concepts from becoming mixed together while preserving contextual understanding.

Purpose:

  • maintain conceptual clarity
  • avoid mixed-context learning
  • preserve insight categorization

Current Domains

frontend
backend
cloud
cloud-concepts
dsa
projects
failures-and-fixes
professional-communication
dbms
nosql
reasons-behind-thoughts
ai-and-ml
meta-learning

8. Philosophy Layer

The platform intentionally includes non-content pages:

/why-this-exists
/how-to-use-insights

Purpose:

  • explain system intent
  • guide reading methodology
  • prevent passive consumption

This transforms the platform from:

content archive

into:

structured engineering learning system

9. Connected Platform Architecture

The homepage includes access to:

  • LGC Systems
  • Founder Portfolio

Purpose:

  • connect ecosystem-level systems
  • preserve platform hierarchy
  • avoid homepage overload

The architecture intentionally avoids:

  • exposing all systems directly
  • turning homepage into a directory

10. Mobile Development Workflow

The platform supports real-device testing through:

vite --host

Purpose:

  • responsive verification
  • touch interaction testing
  • layout validation
  • mobile UX debugging

This enables:

  • laptop + phone simultaneous testing
  • real-world responsive iteration

11. Design Decisions

Markdown-first approach

Reason:

  • fast writing workflow
  • minimal UI duplication
  • portable content system

Serverless API architecture

Reason:

  • lightweight backend
  • deployment simplicity
  • filesystem-based rendering

Public asset strategy

Assets stored in:

client/public/

Reason:

  • direct browser accessibility
  • no image API overhead
  • predictable rendering paths

Controlled rendering model

Purpose:

  • enforce consistent UX
  • prevent layout instability
  • preserve reading structure

12. Constraints

The platform depends on:

  • correct folder structure
  • valid markdown formatting
  • consistent image paths
  • stable route naming
  • serverless filesystem access

If these fail:

  • rendering behavior breaks
  • insight loading fails
  • layout inconsistencies occur

13. What This System Is Not

This platform is not:

  • a CMS
  • a drag-drop builder
  • a database-driven content platform
  • a WYSIWYG editor

It is:

a structured engineering insight rendering platform

14. Summary

The architecture works by:

  • keeping content simple
  • keeping rendering controlled
  • keeping navigation intentional
  • keeping logic lightweight

This separation enables:

  • scalability
  • maintainability
  • clarity
  • structured learning
  • reusable engineering understanding

15. Architectural Direction

Future evolution may include:

  • metadata-driven insights
  • search layer
  • insight tagging
  • graph relationships between insights
  • domain analytics
  • insight dependency mapping

while preserving:

markdown-first structured engineering thinking

16. Meta Learning Architecture

The platform separates:

Domain Knowledge

from:

Cross-Domain Insight

Example:

AI & ML
    ↓
Embedding Exercise
    ↓
Insight Discovered:
"Syntax Correct ≠ Logic Correct"
    ↓
Stored In:
Meta Learning

Meta Learning exists to preserve insights discovered while learning one domain but applicable across many domains.

This prevents valuable engineering lessons from becoming trapped inside a single technical category.

Purpose:

  • preserve transferable understanding
  • capture engineering thinking patterns
  • store cross-domain realizations
  • improve long-term learning quality

The architecture therefore supports two forms of knowledge:

Domain-Specific Knowledge

and

Domain-Independent Learning Insights

This distinction enables the platform to evolve beyond a traditional note-taking system into a structured engineering understanding system.

The Meta Learning domain serves as a knowledge abstraction layer where insights are categorized based on applicability rather than origin.

Author

Ramalingam Jayavelu
Founder & Builder — LGC Systems

Focused on:

  • engineering learning systems
  • structured insight extraction
  • debugging-driven understanding
  • system-first thinking

Platform

Learn With Linga — Engineering Insights Version 1.1
Part of the LGC Systems ecosystem.