This repository is the source of truth for a structured Python-learning knowledge base and a statically compiled website that presents that knowledge base.
The architecture has two deliberately separated concerns:
- Learning content lives under
notes/,practice/, andprojects/. - Presentation lives under
website/and is compiled with Vite + React + TypeScript into static files for deployment on Cloudflare Pages.
The website is not the source of truth. It is a generated presentation layer over the repository content.
Core rule: content must remain useful even if the
website/directory is removed.
.
├── LICENSE
├── README.md
├── archive/
│ ├── extra/
│ ├── important-ques/
│ ├── old-notes/
│ ├── old-practice-que/
│ └── old-practice-que-mysol/
├── notes/
│ ├── index.md
│ ├── metadata.json
│ ├── notes-tracker.py
│ ├── 00-Basics/
│ │ ├── 00-Intro-and-Internal-Working/
│ │ │ ├── 00-LowLevelExecution.md
│ │ │ ├── 00-reference-file-1.py
│ │ │ ├── 01-MultilangIntegration.md
│ │ │ └── ...
│ │ └── ...
│ └── ...
├── practice/
│ ├── index.md
│ ├── 00-Basics/
│ │ └── 00-Intro-and-Internal-Working/
│ │ ├── 00-LowLevelExecution.md
│ │ └── ...
│ └── ...
├── projects/
│ └── index.md
└── website/
├── AGENTS.md
├── ARCHITECTURE.md
├── DESIGN.md
├── package.json
├── tsconfig.json
├── vite.config.ts
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ ├── types/
│ │ └── content.ts
│ ├── services/
│ │ └── contentService.ts
│ ├── components/
│ │ ├── animations/
│ │ │ ├── RibbonFieldBackground.tsx
│ │ │ └── EmeraldHorizonBackground.tsx
│ │ ├── layout/
│ │ │ ├── Navbar.tsx
│ │ │ ├── LinksDropdown.tsx
│ │ │ └── Footer.tsx
│ │ ├── notes/
│ │ │ ├── TopicSidebar.tsx
│ │ │ ├── TableOfContents.tsx
│ │ │ ├── Breadcrumbs.tsx
│ │ │ ├── PrevNextNav.tsx
│ │ │ ├── ReferenceFileList.tsx
│ │ │ └── CodeViewerModal.tsx
│ │ ├── donation/
│ │ │ └── UpiModal.tsx
│ │ └── common/
│ │ └── EmptyState.tsx
│ ├── pages/
│ │ ├── HomePage.tsx
│ │ ├── NotesExplorerPage.tsx
│ │ ├── NoteDetailPage.tsx
│ │ ├── PracticePage.tsx
│ │ ├── ProjectsPage.tsx
│ │ ├── LinksPage.tsx
│ │ ├── DonatePage.tsx
│ │ └── NotFoundPage.tsx
│ └── styles/
│ └── globals.css
└── dist/
The archived material (archive/) is intentionally outside the active information architecture. It must not be automatically surfaced in the public notes navigation unless explicitly migrated.
Markdown and Python source files are canonical learning artifacts. Website code must consume them rather than duplicate their content.
Numeric prefixes (NN-) encode sibling ordering. They are structural, not display text.
Example:
00-syntax-and-basics/
01-control-flow/
02-data-structures/
Within a topic:
00-variables-and-datatypes/
01-operators/
Within a note group:
00-integer.md
01-float.md
02-string.md
The website displays the human-readable name after removing exactly the leading numeric ordering prefix and separator.
notes/index.md and notes/metadata.json are generated from the active content tree and canonical note metadata. Manual edits to generated sections must not be required for correctness.
The production website must not require a server, API, database, Node.js runtime, or server-side rendering at request time. Node.js is build tooling only.
Vite's production build produces a static-hosting-ready bundle in dist by default. Cloudflare Pages supports React builds with npm run build and dist as the build directory. See the official documentation in the Source References section.
Repository scanning, metadata generation, Markdown extraction, heading extraction, reference-file resolution, and route manifest generation should happen at build time. The browser receives already-structured content/data.
Repository files
│
├── notes/*.md
├── notes/*.py
├── notes/metadata.json
└── notes/index.md
│
▼
Content/build pipeline
│
▼
typed website data
│
▼
React components
│
▼
Vite production build
│
▼
dist/
│
▼
Cloudflare Pages
The browser must never need to scan the Git repository itself.
The active learning hierarchy is deliberately limited to three semantic levels:
Python Learning
└── 1.1 Syntax & Basics
└── 1.1.1 Variables & Data Types
├── Integer
├── Float
└── String
Filesystem representation:
notes/
└── 00-syntax-and-basics/
└── 00-variables-and-datatypes/
├── 00-integer.md
├── 01-float.md
└── 02-string.md
The numeric directory/file prefixes are implementation ordering keys. The semantic hierarchy is represented by directory depth.
Active notes must not introduce arbitrary fourth-level topic directories.
If a concept becomes too large, use additional Markdown headings inside the note or split it into sibling notes rather than creating an uncontrolled fourth taxonomy layer.
notes/index.md is the generated Markdown representation of the active notes tree.
It is designed to serve two audiences:
- humans browsing the repository directly;
- the website build pipeline as a simple, readable navigation manifest.
Example generated representation:
# Python Learning
- Syntax & Basics
- Variables & Data Types
- Integer
- Float
- String
- Operators
- Arithmetic Operators
- Assignment Operators- Scan only the active
notes/content tree. - Ignore
archive/, hidden directories,metadata.json,notes-tracker.py, and unrelated files. - Use numeric prefixes only for sorting.
- Strip the leading
NN-from displayed directory/note names. - Prefer the Markdown frontmatter
titlewhen present? No: the canonical display title is derived from the note filename unless a future explicit title field is introduced by the architecture. This avoids a title-source conflict. - Link each note entry to its website route or repository-relative Markdown path according to the generated index contract. The route representation used by the website must be derived from metadata rather than duplicated manually.
- Preserve deterministic alphabetical/numeric ordering based on the
NN-prefix. - Regeneration must produce byte-for-byte stable output when source files have not changed, apart from explicitly time-stamped generated metadata where applicable.
A filename such as:
00-integer.md
is displayed as:
Integer
Recommended normalization pipeline:
00-variable-name.md
↓
remove extension
↓
remove one leading NN-
↓
replace hyphens/underscores with spaces
↓
human title casing where safe
↓
Variable Name
Do not aggressively rewrite acronyms or user-authored terminology. A future explicit title field may override this behavior if needed.
Each learning note is a Markdown file:
notes/<topic>/<subtopic>/<NN-note-name>.md
Example:
notes/00-syntax-and-basics/00-variables-and-datatypes/00-integer.md
The filename determines ordering and the default display title.
The tracker must canonicalize note frontmatter so that only date and time remain.
Canonical form:
---
date: 2026-08-30
time: "17:54:00+05:30"
---Rules:
- Existing frontmatter is parsed.
dateis retained if valid; otherwise the tracker inserts the current date.timeis retained if valid; otherwise the tracker inserts the current local time with timezone offset when possible.- All other YAML keys are removed.
- No second YAML frontmatter block may be created.
- If the Markdown file has no frontmatter, create it at the beginning.
- Content below frontmatter must be preserved byte-for-byte as far as practical; the tracker should not rewrite ordinary Markdown prose merely because metadata is normalized.
- Date/time normalization must be deterministic and documented.
- The tracker should update date/time only when creating missing metadata, not on every run. Otherwise every tracker run would dirty unchanged notes and create unnecessary Git changes.
date and time are content-file metadata. metadata.json may additionally contain generated/build metadata such as path, slug, headings, hash, order, references, and generation timestamp. These are separate layers and must not be copied into Markdown YAML.
A Markdown note may have source/reference Python files beside it.
Example:
00-integer.md
00-reference-file-1.py
00-reference-file-2.py
Reference files share the note's NN prefix.
For a note:
00-integer.md
candidate reference files are:
00-reference-file-1.py
00-reference-file-2.py
...
The tracker should record explicit references in metadata in sorted order.
The NN-reference-file-K.py convention is intentionally scoped to sibling files. The tracker must never assume that an arbitrary .py in the directory belongs to the Markdown note.
The note page exposes references in the right-side overview panel under a separate Reference Files section.
Clicking a reference file:
- must not navigate away from the note;
- opens an in-page code viewer/overlay/panel;
- displays syntax-highlighted Python;
- provides Copy;
- provides Download;
- uses the original reference filename for download.
The browser download must be generated from repository content packaged into the static build. There must be no runtime server call.
metadata.json is the machine-readable content index used by the website build.
It is generated by notes/notes-tracker.py and must not be hand-maintained.
The metadata file should make the website deterministic without repeatedly discovering repository structure at runtime.
Top-level:
{
"schemaVersion": 1,
"generatedAt": "2026-08-30T17:54:00+05:30",
"contentRoot": "notes",
"sections": {
"notes": []
}
}Each topic node should contain enough information to render navigation:
{
"id": "notes/00-syntax-and-basics/00-variables-and-datatypes/00-integer",
"type": "note",
"order": 0,
"name": "00-integer.md",
"title": "Integer",
"slug": "integer",
"relativePath": "00-syntax-and-basics/00-variables-and-datatypes/00-integer.md",
"route": "/notes/syntax-and-basics/variables-and-datatypes/integer",
"date": "2026-08-30",
"time": "17:54:00+05:30",
"headings": [],
"references": [],
"contentHash": "..."
}The exact JSON implementation may evolve, but these concepts should remain available:
- stable identity;
- type (
topic,subtopic,noteor equivalent); - numeric order;
- display title;
- relative source path;
- canonical route;
- frontmatter date/time;
- extracted Markdown headings;
- reference Python files;
- content hash;
- schema version.
metadata.json should contain structure and indexes, not full note bodies. This avoids a second copy of every note and reduces generated-file churn.
The website must not use array indexes as durable identities.
Prefer a normalized repository-relative path as the base ID:
notes/00-syntax-and-basics/00-variables-and-datatypes/00-integer.md
The route is derived from the same semantic path after removing ordering prefixes.
Example:
/notes/syntax-and-basics/variables-and-datatypes/integer
- route generation must be deterministic;
- route components must be URL-safe;
- ordering prefixes must never appear in public URLs;
- renaming a note may intentionally change its route;
- route collisions must fail the build rather than silently overwrite one note.
If route stability across renames becomes important later, add explicit stable IDs to generated metadata rather than relying on filenames.
The website must render the original Markdown semantics rather than maintain hand-written React pages for individual notes.
Recommended build-time flow:
Markdown file
↓
frontmatter parse
↓
Markdown parse
↓
heading extraction
↓
AST / sanitized HTML representation
↓
typed note model
↓
React renderer
Support at minimum:
- headings H1-H6;
- paragraphs;
- emphasis/strong;
- ordered and unordered lists;
- links;
- blockquotes;
- inline code;
- fenced code blocks;
- horizontal rules;
- tables where required;
- task lists if used;
- safe raw HTML handling if enabled.
Markdown is content, but it is still untrusted input from a tooling perspective. Do not blindly inject unsanitized HTML. Any raw HTML support must be explicitly sanitized or disabled.
Every note page follows the same information architecture.
┌──────────────────────────────────────────────────────────────┐
│ Navbar │
├──────────────┬───────────────────────────┬───────────────────┤
│ Topic │ Actual Markdown Note │ Overview / TOC │
│ Navigation │ │ │
│ │ │ Headings │
│ current note │ │ │
│ highlighted │ │ Reference Files │
│ │ │ │
├──────────────┴───────────────────────────┴───────────────────┤
│ Footer │
└──────────────────────────────────────────────────────────────┘
Shows the overall topic/subtopic hierarchy.
Requirements:
- current note highlighted;
- collapsible/hideable;
- current branch automatically expanded;
- keyboard accessible;
- does not lose current location when toggled;
- navigation derived from metadata.
Displays the exact Markdown content in styled rendered form.
Requirements:
- typography optimized for reading code and explanations;
- code blocks with copy controls;
- anchorable headings;
- stable heading IDs;
- preservation of code formatting;
- responsive behavior for smaller screens.
The overview is generated from the headings inside the current Markdown document.
Example:
Overview
Introduction
Syntax
Examples
Common Mistakes
Reference Files
integer-reference-file-1.py
integer-reference-file-2.py
Clicking an overview heading scrolls to the corresponding heading in the current note.
- Do not hard-code the overview.
- Exclude the document title when it is redundant with the page title.
- Preserve heading nesting.
- Generate collision-safe anchor IDs.
- Duplicate heading text must not produce duplicate IDs.
Global navigation:
Python Learning
Notes
Projects
Practice
Links
Donate
GitHub icon + current repository star count
The homepage includes:
- Hero section;
- repository/learning identity;
- introductory details;
- learning-topic discovery;
- calls to explore notes/projects/practice;
- repository/GitHub information;
- footer;
- the supplied visual background/hero/code content when provided later.
Visual rules are defined in website/DESIGN.md; architecture must not duplicate visual specifications there.
Shows the nested topic hierarchy generated from notes/index.md / metadata.json.
Clicking a topic or note must lead directly to its generated note route.
These are architectural placeholders for now.
The same content-driven principles should eventually be applied:
projects/
practice/
but their detailed schemas are intentionally deferred to a later implementation phase.
A static collection of external links/resources. It should not require a backend.
A static informational/payment-link destination. Any payment/QR behavior belongs to DESIGN.md and the later UI implementation, not this architecture contract.
The navbar may display the repository's current public star count.
Because the site is static, this data cannot depend on a runtime API request if the goal is a serverless/static page with deterministic offline behavior.
Recommended architecture:
GitHub repository metadata
↓
build-time fetch or explicitly supplied build variable
↓
static generated metadata
↓
website
Requirements:
- build must remain successful when the star-count source is temporarily unavailable;
- show a safe fallback rather than a broken UI;
- do not expose private credentials;
- do not put GitHub tokens in client-side code;
- optionally cache the last successful value for build resilience.
A future automation workflow can refresh this generated metadata on a schedule, but that is an enhancement and not required for the initial architecture.
The repository and website must have a clear build boundary.
Recommended layout inside website/:
website/
├── src/
├── public/
├── scripts/
├── package.json
├── tsconfig.json
├── vite.config.ts
└── ...
The production output is:
website/dist/
or the configured root-equivalent Vite output directory.
Phase 1 Validate repository/content
Phase 2 Normalize note frontmatter
Phase 3 Generate notes/metadata.json
Phase 4 Generate notes/index.md
Phase 5 Load content into website build
Phase 6 Validate routes/references/headings
Phase 7 Vite production build
Phase 8 Optional static preview
The exact orchestration can be implemented as npm scripts later, e.g.:
npm run content:check
npm run content:generate
npm run build
npm run preview
The final production artifact must be deployable as a static directory.
The website source lives in website/, but its content source lives in notes/.
This is intentional and must not be “simplified” by moving the notes into website/src.
Two supported implementation patterns exist:
Website build tooling directly resolves repository files during build.
website build script
↓
../notes
A build script copies/normalizes only the required static content into a generated directory under website/ before Vite runs.
../notes
↓
website/.generated/
↓
Vite
Pattern B is preferred when Vite's filesystem sandboxing, globbing, or deployment packaging would otherwise make imports from outside the website root fragile.
Generated staging content must never become the canonical source.
The build must fail loudly on structural errors.
At minimum validate:
- invalid numeric prefixes;
- duplicate sibling order numbers;
- missing
.mdnote files where expected; - malformed reference-file names;
- unsupported file types in active note folders.
- unexpected topic depth;
- empty topic directories;
- duplicate semantic titles where route generation would collide;
- malformed directory names;
- forbidden hidden/system files.
- malformed frontmatter;
- missing
dateortimeafter normalization; - unsupported YAML fields remaining in frontmatter;
- invalid date/time values.
- reference file points to no matching note;
- duplicate reference names;
- unreadable Python files;
- unsafe path traversal attempts.
- route collisions;
- missing referenced content;
- broken Markdown links when those are declared to be validated;
- duplicate heading IDs;
- missing current-note references in navigation.
A content error should not be silently converted into a broken page.
All repository-relative paths must be normalized and validated before use.
Reject or safely ignore:
../../outside-file.py
..\\outside-file.py
absolute paths
symlink escapes outside the repository/content root
The tracker and website build tools must operate only within their declared roots.
Do not trust filenames when constructing output paths without validation.
Ordering is encoded by numeric prefixes.
Accept exactly the intended leading numeric ordering pattern, for example:
^(\d+)-(.+)$Use the numeric value for ordering rather than lexicographical filename ordering.
This avoids:
1-topic
10-topic
2-topic
being interpreted incorrectly.
For consistency, active content should normally use two-digit prefixes (00–99). The architecture may support more digits, but the website must not depend on a fixed width.
Two siblings with the same numeric prefix should be a validation error unless an explicit future tie-breaking policy is introduced.
The first version should implement client-side search over generated static metadata/content.
No server is required.
Recommended search document fields:
- title;
- topic path;
- note slug;
- headings;
- normalized note text;
- tags later if introduced;
- reference filenames where useful.
For small-to-medium learning-note collections, a static in-browser index is sufficient.
If the repository becomes very large, generate a compact search index at build time rather than parsing every Markdown file in the browser.
Architecture-level requirements:
- semantic HTML;
- keyboard navigation;
- visible focus states;
- accessible names for icon-only buttons;
- no information conveyed by color alone;
- skip-to-content mechanism;
- dialog/overlay focus management for reference code viewers;
- reduced-motion support;
- reasonable contrast;
- responsive behavior without hiding critical content.
Visual implementation belongs in DESIGN.md.
Because the site is content-heavy and static:
- avoid loading every full note into the initial page unnecessarily;
- prefer route-level/content-level loading where practical;
- keep metadata compact;
- do not ship duplicate Markdown and HTML copies unless justified;
- code highlighting should not dominate initial bundle cost;
- optimize repository images and other static assets;
- use hashed Vite assets for cache safety.
Large notes should not make the global navigation payload unnecessarily large.
The site should use clean routes such as:
/
/notes
/notes/syntax-and-basics/variables-and-datatypes/integer
/projects
/practice
/links
/donate
Routes should be handled as an SPA where the deployment configuration supports fallback to the root document. Cloudflare Pages documents SPA behavior in which, without a top-level 404.html, unmatched paths can be routed to the application root.
Even with SPA fallback, the application must provide its own in-app 404 state for unknown logical routes.
Opening a note URL directly, refreshing it, or entering it in a new tab must produce the same note page as navigating there from /notes.
The current note is determined from the URL, not only React in-memory state.
This ensures:
- refresh persistence;
- shareable links;
- browser back/forward support;
- deep linking;
- consistent current-note highlighting.
Left navigation collapse state may be persisted locally, but persisted UI state must never be required to understand the current content.
Reference code is content, not a second page type.
Note Page
└── Reference Files
└── Code Viewer
├── filename
├── syntax highlighting
├── copy
└── download
The code viewer should support:
- long-file scrolling;
- line wrapping toggle if desired;
- line numbers if desired;
- copy feedback;
- accessible close behavior;
- escape-to-close for overlays;
- preserved scroll position in the underlying note;
- downloadable content with the original
.pyfilename.
Download must use exact file content packaged at build time.
The practice/ domain mirrors the exact same topic/subtopic directory hierarchy as notes/:
notes/
└── NN-topic/
└── NN-subtopic/
├── NN-note-name.md
└── NN-reference-file-1.py
practice/
└── NN-topic/
└── NN-subtopic/
├── NN-note-name.md
└── ...
When a file in practice/ exists at the identical relative path structure and matches the slug/name of a note in notes/ (e.g. practice/00-Basics/00-Intro-and-Internal-Working/00-LowLevelExecution.md vs notes/00-Basics/00-Intro-and-Internal-Working/00-LowLevelExecution.md):
- Automatic Connection: The tracker and metadata service detect that these two files represent a Connected Theory & Practice Pair.
- Metadata Fields:
- The note metadata node includes
practiceRoute: "/practice/basics/intro-and-internal-working/lowlevelexecution"(ornullif no matching practice exercise exists). - The practice metadata node includes
noteRoute: "/notes/basics/intro-and-internal-working/lowlevelexecution".
- The note metadata node includes
- UI Integration:
- On the Note Page (
NoteDetailPage): The right-side rail / TOC panel renders an actionable "Practice Related Exercises" button/card linking directly to the practice exercise. - On the Practice Page: The problem statement header renders a "View Theory Notes" link/button jumping straight back to the foundational theory.
- On the Note Page (
To provide an uncompromising mobile experience without desktop compromises, the website employs specific architectural patterns:
In modern CSS, applying backdrop-filter, filter, or transform to a container creates a new containing block for all its descendants, even those with position: fixed. To prevent fixed mobile drawers and overlays from being constrained/clipped by <header> (height 56px), all mobile overlays are rendered directly to document.body using createPortal:
// Pattern used in Navbar.tsx for the mobile navigation drawer
{mobileMenuOpen && typeof document !== 'undefined' && createPortal(
<div className="mobile-nav-portal" style={{ position: 'fixed', top: 'var(--navbar-height)', left: 0, right: 0, bottom: 0, zIndex: 99999 }}>
{/* Navigation Links, Practice jump, Donate CTA, GitHub Star link */}
</div>,
document.body
)}- Desktop (
>= 1024px): Static sticky left rail (280px width) staying in-flow. - Mobile & Tablet (
< 1024px): Off-canvas slide-out drawer (position: fixed; left: 0; top: 0; bottom: 0; width: min(320px, 85vw); z-index: 600;), with dark backdrop blur overlay (rgba(0,0,0,0.75)), body scroll locking (document.body.style.overflow = 'hidden'), auto-closing upon tapping any note link, and a floatingTopicspill button when closed.
- On screens
< 1100pxwhere the right-hand TOC rail is hidden, a collapsible "On this page" Table of Contents accordion is inserted directly before the markdown note body so mobile users retain heading-jump capabilities.
- Breadcrumbs and code viewer containers use
overflow-x: autowith-webkit-overflow-scrolling: touchandwhite-space: nowrap. - All card grids use
grid-template-columns: repeat(auto-fit, minmax(270px, 1fr))to guarantee zero horizontal overflow blowout on small phone screens (320px–375px).
The website incorporates two continuous, GPU-accelerated WebGL backgrounds designed to blend seamlessly with the dark developer canvas:
- Implemented in custom GLSL shaders rendered on a WebGL canvas.
- Dynamically cycles hues over time with subtle pointer/mouse drift.
- Responsive sizing: maintains aspect ratio on desktop while expanding dynamically to content height on mobile (
aspect-ratio: autoon mobile withpadding: clamp(48px, 8vw, 72px) 16px).
- Implemented with Three.js rendering an undulating wave plane with custom shaders.
- Zero Vignette Rule: Always initialized with
vignette = 0to preserve pure edge-to-edge dark canvas harmony. - Synchronized hue cycling with the hero component.
Any developer or AI agent can replicate this entire learning notes & website platform by following this deterministic four-tier architecture:
Tier 1: Markdown & Python Content Root (notes/, practice/, projects/)
├── Numeric prefix ordering (NN-topic/NN-subtopic/NN-note.md)
├── Minimal YAML frontmatter (date, time)
└── Sibling Python files (NN-reference-file-K.py)
Tier 2: Content Generation Engine (notes/notes-tracker.py)
├── AST heading extraction
├── Slugification & route computation
├── JSON index compilation (notes/metadata.json)
└── Markdown roadmap manifest (notes/index.md)
Tier 3: Presentation & Component Layer (website/src/)
├── Content service & search indexer (contentService.ts)
├── Responsive 3-column note layout with mobile drawer portals
├── WebGL Ribbon & Three.js Emerald shaders
├── In-page code viewer modal & UPI donation system
└── Pure CSS variables & dark canvas styling (globals.css)
Tier 4: Static Compilation & Deployment (Vite + Cloudflare Pages)
├── Pre-build script: python3 ../notes/notes-tracker.py
├── Static compilation: vite build -> dist/
└── Cloudflare Pages static hosting with SPA deep-link fallback
ARCHITECTURE.md defines:
- file structure;
- content contracts;
- data flow;
- build pipeline;
- routing;
- validation;
- component responsibilities at a structural level;
- static-hosting constraints.
DESIGN.md defines:
- visual language;
- typography;
- spacing;
- colors;
- motion;
- component appearance;
- hero/footer visuals;
- interaction styling;
- responsive visual behavior.
Do not duplicate visual decisions into this file. If a visual requirement conflicts with the architectural constraints, preserve the architecture and adapt the visual implementation.
AGENTS.md is the operational rulebook for AI agents and coding workflows.
It defines:
- how to inspect the repository;
- which files are authoritative;
- what must be validated;
- what agents may change;
- approval requirements;
- commit requirements;
- how to update itself when new durable preferences are discovered.
ARCHITECTURE.md should remain stable and descriptive rather than becoming a task log.
A scalable website should roughly separate:
src/
├── app/
│ ├── router
│ ├── providers
│ └── app-shell
├── components/
│ ├── navigation/
│ ├── note/
│ ├── markdown/
│ ├── code-viewer/
│ ├── common/
│ └── layout/
├── pages/
│ ├── home
│ ├── notes
│ ├── note
│ ├── projects
│ ├── practice
│ ├── links
│ └── donate
├── content/
│ ├── types
│ ├── loaders
│ └── adapters
├── lib/
│ ├── slug
│ ├── headings
│ ├── paths
│ └── validation
└── styles/
This is a conceptual boundary, not a mandate to create every folder immediately.
Avoid a giant App.tsx that owns routing, Markdown parsing, navigation, GitHub data, and visual state simultaneously.
For Cloudflare Pages, the expected static deployment contract is:
Repository root
↓
install dependencies
↓
content generation/validation
↓
npm run build
↓
website/dist/
↓
Cloudflare Pages
Cloudflare's React Pages guidance uses npm run build and dist for deployment, and Pages can automatically rebuild when connected to a Git repository.
Vite's production build is designed for static hosting and outputs dist by default.
Do not introduce SSR, API routes, server-only rendering, database requirements, or runtime backend dependencies unless this architecture is deliberately revised.
The project should eventually contain four distinct test layers:
Validate:
- hierarchy;
- filenames;
- frontmatter;
- references;
- generated index;
- metadata schema.
Validate pure functions:
- prefix parsing;
- title normalization;
- route generation;
- heading ID generation;
- reference association.
Run a clean production build and ensure:
- every metadata note resolves;
- every route resolves;
- every reference file is packaged;
- no route collision exists;
- no broken imports exist.
Eventually test:
- topic navigation;
- deep links;
- note overview scrolling;
- copy/download behavior;
- responsive navigation;
- reference viewer;
- not-found state.
Risk: tracker leaves old metadata behind.
Resolution: canonicalize frontmatter to date + time only.
Risk: notes become inconsistent.
Resolution: insert missing values once; do not refresh existing values on every run.
Risk: unstable navigation.
Resolution: fail validation.
Risk: parser assumes exactly two digits.
Resolution: parse one-or-more digits; display logic strips the complete numeric prefix.
Risk: undetermined order.
Resolution: validation error for active notes.
Risk: one note becomes unreachable.
Resolution: fail build and print both conflicting source paths.
Risk: overview links collide.
Resolution: deterministic slug suffixes, e.g. example, example-2, example-3.
Risk: orphaned source code.
Resolution: either report as orphaned during validation or ignore explicitly according to a documented rule. Do not silently associate it with the wrong note.
Risk: stale metadata.
Resolution: regenerate metadata from the filesystem every content build.
Risk: website links to dead content.
Resolution: metadata is regenerated from current filesystem state; no stale-note retention.
Risk: changes disappear.
Resolution: generated regions/files are overwritten by the tracker. Agents must not manually “fix” generated output instead of fixing the source.
Risk: unsafe HTML rendering.
Resolution: sanitize or disable raw HTML rendering.
Risk: metadata and routes differ between environments.
Resolution: normalize all repository paths to forward-slash POSIX form in metadata, regardless of host OS.
Risk: URL and filesystem normalization differences.
Resolution: preserve source filenames, but generate normalized URL slugs and validate collisions.
Risk: works on case-sensitive Linux but collides on case-insensitive Windows.
Resolution: validation should detect case-insensitive path/route collisions.
Risk: content escapes the intended tree.
Resolution: reject links that resolve outside the declared content root.
Risk: invisible topics.
Resolution: empty active topic folders should fail validation or be reported clearly; do not generate empty navigation nodes silently.
Risk: large browser bundles.
Resolution: consider build-time route splitting or generated per-note content chunks if scale requires it.
Risk: unrelated site builds fail.
Resolution: star count is non-critical; use fallback/cached data and continue.
Risk: refreshing /notes/.../integer produces a 404.
Resolution: use the deployment's SPA fallback configuration and maintain an application-level 404 state.
Risk: current note works but UI context disappears.
Resolution: derive current note from URL and optionally persist only non-critical UI preferences.
Risk: route and index change unexpectedly.
Resolution: treat filename/directory changes as intentional content-structure changes; regenerate metadata and test route output.
Risk: malformed metadata during simultaneous edits.
Resolution: tracker should fail atomically where practical and avoid writing half-generated JSON/index files.
The architecture intentionally leaves room for:
- generated RSS/feed-like static indexes;
- per-note previous/next navigation;
- breadcrumbs;
- last-updated indicators;
- reading-time estimates;
- note tags;
- topic progress indicators;
- full-text search index;
- command palette/search UI;
- favorites/bookmarks stored locally;
- print-friendly note views;
- static sitemap generation;
- JSON-LD/SEO metadata generation;
- Open Graph metadata;
- offline caching/PWA if later desired;
- build-time link checking;
- automatic content statistics;
- GitHub repository release/commit metadata;
- practice/project schemas built on the same content model.
These are enhancements, not reasons to violate the static-first architecture.
The initial architecture does not require:
- a backend server;
- a database;
- authentication;
- CMS software;
- runtime Markdown fetching from GitHub;
- runtime GitHub API calls for essential functionality;
- SSR;
- server-side note storage;
- manual per-note React components.
The initial implementation is architecturally complete when:
notes/follows the defined hierarchy.notes/notes-tracker.pycan normalize frontmatter without destroying note content.notes/metadata.jsonis generated deterministically.notes/index.mdis generated from active notes.- Numeric prefixes are used only for ordering and are hidden from displayed names/routes.
- Notes render from Markdown automatically.
- Note headings generate the right-side overview.
- Reference Python files appear beside the overview.
- Reference files can be viewed, copied, and downloaded without a backend.
- The left topic navigator highlights the current note and can be hidden.
/notesexposes the nested learning hierarchy.- Direct note routes work after refresh on static hosting.
- The website builds with Vite into a static output directory.
- Cloudflare Pages can deploy the resulting
distoutput. - Agents follow
AGENTS.mdand do not commit website changes before explicit user approval. - Visual implementation follows
DESIGN.mdwithout architectural duplication.
- Vite — Static Site Deployment: https://vite.dev/guide/static-deploy
- Vite — Production Build: https://vite.dev/guide/build
- Cloudflare Pages — React: https://developers.cloudflare.com/pages/framework-guides/deploy-a-react-site/
- Cloudflare Pages — Serving Pages / SPA Rendering: https://developers.cloudflare.com/pages/configuration/serving-pages/