LearnAI — Codebase Architecture Documentation

Status: ✅ Complete (Foundation Phase)
Last Updated: March 10, 2026
Document Version: 1.0

---

📚 Documentation Index

Welcome to the codebase reference! This directory contains standardized documentation of the LearnAI system architecture.

Quick Reference

Document	Purpose	Audience
stack.md	Technology stack & dependencies	Developers, DevOps
structure.md	Directory layout & file organization	All developers
architecture.md	System design & data flow diagrams	Architects, senior devs
conventions.md	Coding & content standards	All developers
integrations.md	External services & APIs	Integration specialists
testing.md	Testing strategy & QA approach	QA engineers, testers
concerns.md	Known issues & technical debt	Tech leads, refactoring

---

🚀 Quick Start for New Team Members

1. Understand the Project (5 minutes)

Read the Executive Summary in concerns.md#conclusion to understand:

• Current project status
• What's built vs. planned
• Key components

2. Set Up Local Environment (15 minutes)

Follow stack.md§Runtime Stack:

bundle install    # Ruby dependencies
npm install       # Node.js dependencies
npm run dev       # Start dev server (Gulp + Jekyll)
# Site available at http://localhost:3000

3. Explore the Structure (10 minutes)

Navigate folders per structure.md:

• _posts/ — Blog content (9 published posts: Tools category + Career)
• _layouts/ — Page templates
• _includes/ — Reusable components
• assets/ — Compiled CSS/JS/images
• src/ — Source files for Gulp processing
• docs/ — Project documentation

4. Read Relevant Docs

If you're writing content: → Read conventions.md (Front-matter spec, content style, SEO)

If you're building features: → Read architecture.md (System design, data flow)

If you're integrating services: → Read integrations.md (APIs, credentials, setup)

If you're debugging: → Read concerns.md (Known issues, limitations)

---

📊 Project Status

Current Phase: Foundation (Phase 1–2)

Phase	Name	Status	Impact
Phase 1	Project Setup & Documentation	✅ COMPLETE	Site infrastructure ready
Phase 2	Content Architecture & UI	⏳ IN PROGRESS	Series navigation, badges
Phase 3	AI Agent Pipeline	⏳ PLANNED	Autonomous content generation
Phase 4	First Content Wave	⏳ PLANNED	50+ posts published
Phase 5	Polish & SEO	⏳ PLANNED	Analytics, comments, optimization
Phase 6	Portfolio Integration	⏳ PLANNED	Link from main portfolio

See: concerns.md#tier-1-critical-gaps for blocking items.

---

🏗️ System Architecture (30-Second Overview)

GitHub Pages (Static Hosting)
  ↓
Author writes Markdown
  ↓
Commit & push to main
  ↓
GitHub Actions triggers
  │├─ Gulp (CSS/JS processing)
  │└─ Jekyll (Markdown → HTML)
  ↓
Static HTML output deployed
  ↓
Browser loads pre-built HTML + Lunr.js search

Planned Enhancement (Phase 3+):

Author's idea
  ↓
[Agent Pipeline: Orchestrator → Research → SEO → Writer → Formatter]
  ↓
Generates Jekyll-ready .md file
  ↓
(Rest continues as above)

See: architecture.md for detailed flows & diagrams.

---

🛠️ Technology Stack (Quick List)

Layer	Tech	Version
Generator	Jekyll	4.x
Theme	Chirpy	Latest
Build Tool	Gulp	4.0.2
Package Mgmt	npm + Bundler	Latest
Hosting	GitHub Pages	Native
Search	Lunr.js	Built at build time
Analytics	Plausible (planned)	—
AI Backbone	Claude API (planned)	claude-sonnet-4-6

See: stack.md for full breakdown.

---

📁 Key Files & Directories

learn-with-satya/
├── _posts/                 # Blog posts (7 category folders, currently empty)
├── _data/
│   ├── series.yml          # Learning series metadata
│   └── categories.yml      # Category definitions
├── _layouts/ & _includes/  # Jekyll templates (custom components planned)
├── assets/                 # Compiled CSS/JS/images
├── src/                    # Source files (YAML config, JS, SCSS)
├── scripts/
│   └── blog/analyze_blog.py    # Blog quality analyzer (100-point system)
├── docs/
│   ├── codebase/           # **This directory** (7 docs)
│   ├── LearnHub_PRD.md     # Product requirements
│   ├── LearnHub_TRD.md     # Technical requirements
│   └── WORKFLOW.md         # Integration with Copilot workflow
├── .github/                # GitHub workflows, instructions, skills
├── package.json            # npm dependencies
├── Gemfile                 # Ruby dependencies
└── _config.yml             # Jekyll configuration

See: structure.md for exhaustive directory map.

---

🔑 Key Concepts

Learning Series

An ordered collection of blog posts forming a complete curriculum:

• Example: "AI Fundamentals" (Part 1, 2, 3...)
• Metadata: _data/series.yml
• Navigation: Prev/Next buttons (planned)
• Progress: localStorage tracking (planned)

See: conventions.md§Series-Specific Sections

Categories

7 top-level taxonomies for organizing content:

• AI & Machine Learning
• System Design & Architecture
• Backend Engineering
• DevOps & Cloud
• Frontend & Web
• Career Development
• Dev Tools & Ecosystem

See: conventions.md§Naming Conventions

AgentContext

Shared data structure passed between AI agents:

• Orchestrator sets topic + category
• Research Agent appends insights + sources
• SEO Agent appends outline + keywords
• Writer Agent appends body text
• Formatter Agent assembles final .md file

See: architecture.md§Planned Data Flow

---

⚙️ Common Tasks

Running the Site Locally

npm run dev          # Webpack + Jekyll + BrowserSync
# Visit http://localhost:3000

Creating a Blog Post

(Currently manual; Phase 4 will use agents)

# 1. Create Markdown file
touch _posts/ai/2026-03-10-my-post.md

# 2. Add front-matter + content
# (See conventions.md for template)

# 3. Run analyzer
python scripts/blog/analyze_blog.py _posts/ai/2026-03-10-my-post.md --format markdown

# 4. Iterate until score ≥ 80

# 5. Commit & push
git add _posts/
git commit -m "feat(ai): add my-post"
git push

Building for Production

JEKYLL_ENV=production bundle exec jekyll build
# Output in _site/

Checking for Broken Links

# Coming in Phase 5 (automated)
# For now, manual inspection or use online tools

---

❓ FAQ

Q: Is this site currently live?

A: The infrastructure is ready (GitHub Pages, Jekyll, Gulp), but the site has no content. Deploying now would show an empty homepage. Content generation begins in Phase 4.

Q: How do I add a blog post?

A: Currently manual (conventions.md§Front-Matter). Phase 3–4 will add automated agents to generate posts. Until then, write Markdown directly.

Q: What's the plan for comments?

A: Giscus (GitHub Discussions) — planned for Phase 5. No implementation yet.

Q: How do I set up local dev?

A: See stack.md§Runtime Stack or run:

bundle install && npm install && npm run dev

Q: Can I use custom Jekyll plugins?

A: No — GitHub Pages restricts plugins to an official whitelist. Use Gulp for custom processing instead (current approach).

Q: What's the CI/CD setup?

A: GitHub Actions auto-runs Jekyll on push to main. Deployment to GitHub Pages happens automatically. No manual deploy needed.

---

🚨 Critical Issues

None blocking current work, but See concerns.md§Tier 1:

• No content yet (blocks Phase 4)
• Agents not built (blocks Phase 3)
• Custom components not built (blocks Phase 2)

These are by design — they're planned features, not bugs.

---

📞 Get Help

If you need to understand...

Need	Read	Time
How to set up locally	stack.md	10 min
Where files are	structure.md	15 min
How data flows	architecture.md	20 min
Content standards	conventions.md	20 min
External APIs	integrations.md	15 min
Testing approach	testing.md	15 min
Known issues	concerns.md	15 min

---

📚 Related Documentation

• Product Requirements: .github/docs/LearnHub_PRD.md (what to build)
• Technical Requirements: .github/docs/LearnHub_TRD.md (how to build)
• Workflow Guide: docs/WORKFLOW.md (Copilot integration)
• Blog System Guide: docs/BLOG-SYSTEM-GUIDE.md (learning series features)
• Developer Instructions: .github/instructions/ (8+ guides)
• Copilot Entry Point: .github/copilot-instructions.md

---

✅ Document Checklist

This codebase documentation follows the Acquire Codebase Knowledge skill (.github/skills/acquire-codebase-knowledge/SKILL.md):

• ✅ Fact-First: All information verified against actual code (not hallucinated)
• ✅ Zero Assumptions: Code reviewed; unclear areas marked as [TODO] or [ASK USER]
• ✅ No Hallucinations: No invented file names, patterns, or layers
• ✅ Context-Priority: PRD/TRD reviewed first to understand intent vs. reality
• ✅ All 7 Templates: stack.md, structure.md, architecture.md, conventions.md, integrations.md, testing.md, concerns.md

Verification Status: Phase 1 complete. Ready for Phase 2 development.

---

🎯 Next Steps

1. Read the docs relevant to your work
2. Set up local environment per stack.md
3. Explore folder structure per structure.md
4. Start work on your assigned Phase task
5. Reference conventions & architecture as needed
6. Report issues → update concerns.md

---

Generated: March 10, 2026 using Copilot Codebase Knowledge Skill
Status: ✅ Complete and Verified
Next Review: After Phase 2 completion or when architecture changes