Core Intuition Engine

Distributed Systems Development Roadmap

App Structure Preview

• Unit 1: Introduction
• Unit 2: Architecture
• Unit 3: Processes
• ...and more!

This sidebar simulates your app's main navigation.

Your Step-by-Step Development Journey

Follow these granular steps to build your "Core Intuition Engine" app. Each step is designed to be a small, achievable task.

Phase 1: Project Setup & Core Structure (Foundation)

• 1.1. Install Node.js and npm (if not already installed).
• 1.2. Open your terminal.
• 1.3. Create a new Next.js project: npx create-next-app@latest distributed-systems-app --typescript --tailwind --eslint (choose "No" for App Router for simplicity, "Yes" for src directory).
• 1.4. Navigate into the project directory: cd distributed-systems-app.
• 1.5. Initialize a Git repository: git init.
• 1.6. Create your first commit: git add . && git commit -m "Initial Next.js project setup".
• 2.1. Install Convex CLI: npm install -g convex.
• 2.2. Login to Convex: npx convex login.
• 2.3. Create a new Convex project: npx convex init (choose "Next.js" integration).
• 2.4. Verify Convex setup by checking convex/ directory and convex.json.
• 2.5. Create your first Convex function file: touch convex/myFunctions.ts.
• 2.6. Add a simple query function in convex/myFunctions.ts (e.g., export const hello = query({ handler: async () => "Hello from Convex!" });).
• 2.7. Deploy initial Convex functions: npx convex deploy.
• 2.8. Connect Next.js to Convex: Ensure ConvexProvider is wrapping your _app.tsx or layout.tsx.
• 2.9. Make a basic call from a React component to your Convex function to verify connection.
• 2.10. Remove test code after verification.
• 2.11. Commit: git commit -m "Integrated Convex backend".
• 3.1. Open your project's src/ directory.
• 3.2. Create a file for syllabus data: src/data/syllabus.ts.
• 3.3. Define a TypeScript interface for a "Unit" and "Topic" (as detailed in previous response).
• 3.4. Populate src/data/syllabus.ts with placeholder data for Unit 1.1 Characteristics (just one topic to start).
• 3.5. Commit: git commit -m "Defined initial data schema and added mock syllabus data".

Phase 2: Core UI & Navigation (Minimum Viable App)

• 4.1. Modify src/app/page.tsx (or src/pages/index.tsx) to display a simple title: "Distributed Systems Intuition Engine".
• 4.2. Create a new component src/components/SyllabusSidebar.tsx.
• 4.3. In SyllabusSidebar.tsx, import your mock syllabus.ts data.
• 4.4. Map over the syllabus array to display each Unit.title as a clickable link/list item.
• 4.5. Implement basic CSS (Tailwind) for a two-column layout in src/app/page.tsx: sidebar on left, main content area on right.
• 4.6. Integrate SyllabusSidebar into src/app/page.tsx's left column.
• 4.7. Commit: git commit -m "Implemented basic layout with syllabus sidebar".
• 5.1. Implement dynamic routing for units in Next.js. Create src/app/unit/[unitId]/page.tsx or src/pages/unit/[unitId].tsx.
• 5.2. In the dynamic unit page component, use useRouter() to get the unitId from the URL.
• 5.3. Filter your mock syllabus.ts data to find the current unit based on unitId.
• 5.4. Display the Unit.title and list its topics (just titles for now).
• 5.5. Update SyllabusSidebar.tsx links to navigate to /unit/[unitId].
• 5.6. Commit: git commit -m "Added dynamic routing for individual units".
• 6.1. Implement nested dynamic routing for topics. Create src/app/unit/[unitId]/topic/[topicId]/page.tsx or src/pages/unit/[unitId]/[topicId].tsx.
• 6.2. In the dynamic topic page, get both unitId and topicId from the URL.
• 6.3. Find the specific topic from your mock data.
• 6.4. Display the Topic.title and Topic.description.
• 6.5. Update the topic list in the Unit page to link to /unit/[unitId]/topic/[topicId].
• 6.6. Commit: git commit -m "Implemented nested dynamic routing for topics".

Phase 3: Content Integration (Core Learning Features)

• 7.1. Enhance the Topic page.
• 7.2. Display Topic.description clearly as "Intuition".
• 7.3. Conditionally display Topic.deepDiveContent under a "Deep Dive" heading if it exists.
• 7.4. Use a markdown rendering library (e.g., react-markdown). Install it: npm install react-markdown remark-gfm.
• 7.5. Update mock data for one topic to include deepDiveContent.
• 7.6. Commit: git commit -m "Displaying intuition and deep dive content".
• 8.1. Create a src/components/CodeSnippetDisplay.tsx component.
• 8.2. In CodeSnippetDisplay.tsx, take codeSnippet as a prop.
• 8.3. Use a syntax highlighting library (e.g., react-syntax-highlighter). Install it: npm install react-syntax-highlighter.
• 8.4. Display code, language, and explanation within the component.
• 8.5. In the Topic page, map over topic.codeSnippets and render CodeSnippetDisplay for each.
• 8.6. Update mock data for one topic to include a codeSnippets array.
• 8.7. Commit: git commit -m "Integrated and styled code snippet display".
• 9.1. Create a src/components/ConceptVisualizer.tsx component.
• 9.2. This component will take visualization data as a prop.
• 9.3. For type: 'image', display an <img> tag. For type: 'text-based', display content within a <pre> tag.
• 9.4. For type: 'svg', embed the SVG directly or load it.
• 9.5. In the Topic page, map over topic.visualizations and render ConceptVisualizer.
• 9.6. Update mock data for one topic to include a simple image or text-based visualization.
• 9.7. Commit: git commit -m "Added basic concept visualizer display".
• 10.1. Create a src/components/GlossaryDisplay.tsx component.
• 10.2. This component takes an array of GlossaryTerm as a prop.
• 10.3. Display each term and its definition in a clear list format.
• 10.4. In the Topic page, conditionally render GlossaryDisplay if topic.glossaryTerms exist.
• 10.5. Update mock data for one topic to include some glossaryTerms.
• 10.6. Commit: git commit -m "Implemented glossary terms display".
• 11.1. Create a src/components/NotesDisplay.tsx component.
• 11.2. This component takes an array of Note as a prop.
• 11.3. Display the content of each note. (No adding/editing functionality yet).
• 11.4. In the Topic page, conditionally render NotesDisplay.
• 11.5. Update mock data for one topic to include some placeholder notes.
• 11.6. Commit: git commit -m "Added display for user notes (static)".
• 12.1. Create a src/components/ExternalLinksDisplay.tsx component.
• 12.2. This component takes an array of ExternalLink as a prop.
• 12.3. Display each link with its url, description, and source. Make the url clickable.
• 12.4. In the Topic page, conditionally render ExternalLinksDisplay.
• 12.5. Update mock data for one topic to include some placeholder externalLinks.
• 12.6. Commit: git commit -m "Implemented display for external resource links (static)".

Phase 4: Data Persistence with Convex

• 13.1. Define your Convex schema. Create convex/schema.ts.
• 13.2. Define tables for units, topics, codeSnippets, visualizations, glossaryTerms, notes, externalLinks. Use Convex's v.id, v.string, v.number, v.array, v.object types.
• 13.3. Deploy your schema: npx convex deploy.
• 13.4. Create Convex mutation functions (e.g., convex/topics.ts, convex/notes.ts) to add, update, delete entries for initial data population.
• 13.5. Write a simple Node.js script or use the Convex dashboard/API to populate your Convex database with the syllabus data.
• 13.6. Commit: git commit -m "Migrated syllabus data to Convex schema and populated DB".
• 14.1. Create Convex query functions to fetch units, topics, and their related sub-contents.
• 14.2. In SyllabusSidebar.tsx, replace the local mock data import with useQuery(api.units.getUnits).
• 14.3. In the Unit page, replace mock data with useQuery(api.topics.getTopicsByUnit, { unitId: router.query.unitId }).
• 14.4. In the Topic page, replace mock data with multiple useQuery calls to fetch the main topic, its code snippets, visualizations, etc.
• 14.5. Remove the local src/data/syllabus.ts file.
• 14.6. Commit: git commit -m "Switched to fetching all syllabus data from Convex".
• 15.1. In convex/notes.ts, create a mutation function addNote.
• 15.2. In the Topic page component, add a text area and a "Save Note" button.
• 15.3. Use useMutation(api.notes.addNote) to call the Convex function when the button is clicked.
• 15.4. Ensure the NotesDisplay component automatically re-renders due to Convex's real-time capabilities.
• 15.5. Commit: git commit -m "Enabled user to add notes, persisted to Convex".
• 16.1. In convex/externalLinks.ts, create a mutation function addExternalLink.
• 16.2. In the Topic page, add a form (input fields for URL, description, source) and a "Add Link" button.
• 16.3. Use useMutation(api.externalLinks.addExternalLink) to save the link to Convex.
• 16.4. Commit: git commit -m "Enabled user to add external links, persisted to Convex".

Phase 5: Enhancements & Polish

• 17.1. Install react-flow-renderer: npm install react-flow-renderer.
• 17.2. In ConceptVisualizer.tsx, add a condition to render ReactFlowProvider and ReactFlow component if visualization.type === 'react-flow'.
• 17.3. Define sample nodes and edges data structure for a distributed system concept.
• 17.4. Update mock data for one topic's visualization to type: 'react-flow' and include appropriate nodes and edges data.
• 17.5. Commit: git commit -m "Integrated react-flow-renderer for advanced visualizations".
• 18.1. Review all components and apply Tailwind CSS utility classes to ensure the app looks good on different screen sizes.
• 18.2. Focus on navigation sidebar collapsing/expanding, content readability, and image/visualizer scaling.
• 18.3. Commit: git commit -m "Implemented responsive design using Tailwind CSS".
• 19.1. Define a consistent color palette using Tailwind's configuration or custom CSS variables.
• 19.2. Apply consistent typography (font sizes, weights) across headings and body text.
• 19.3. Add subtle hover effects for clickable elements.
• 19.4. Commit: git commit -m "Applied consistent basic styling and theming".
• 20.1. For all useQuery and useMutation calls, add isLoading and error states.
• 20.2. Display loading spinners or messages when data is being fetched.
• 20.3. Display user-friendly error messages if data fetching or mutations fail.
• 20.4. Commit: git commit -m "Added loading states and basic error handling".
• 21.1. Add a search input field in the header or sidebar.
• 21.2. Implement a simple client-side search that filters displayed topics by title or description as the user types.
• 21.3. *Advanced (Future):* Implement a Convex search function to search across all topic content if client-side is too slow.
• 21.4. Commit: git commit -m "Implemented basic client-side search for topics".
• 22.1. Add a "Back to Units" link on topic pages.
• 22.2. Highlight the currently active unit and topic in the sidebar.
• 22.3. Implement smooth scrolling to sections within a topic if it gets long.
• 22.4. Commit: git commit -m "Enhanced navigation and user experience".

Phase 6: Future-Proofing & Deployment

• 23.1. Modify your Convex schema to include a subjects table: subjects: defineTable({ name: v.string() }).
• 23.2. Add a subjectId: v.id('subjects') field to your units table.
• 23.3. Create a default "Distributed Systems" subject in Convex.
• 23.4. Update relevant queries to filter by subjectId.
• 23.5. Add a simple subject selector (e.g., a dropdown) in the main layout.
• 23.6. Commit: git commit -m "Refactored schema for multi-subject support".
• 24.1. For the unit and topic pages, consider using Next.js getStaticProps and getStaticPaths or generateStaticParams to pre-render.
• 24.2. Note: User-added notes and links will still be fetched client-side.
• 24.3. Commit: git commit -m "Implemented static site generation for core content pages".
• 25.1. Review your code for cleanliness, consistency, and adherence to React/Next.js best practices.
• 25.2. Break down any large components into smaller, more focused ones.
• 25.3. Ensure prop drilling is minimized.
• 25.4. Add comments where necessary.
• 25.5. Commit: git commit -m "Performed comprehensive code review and refactoring".
• 26.1. Thoroughly test all features: navigation, content display, adding notes, adding links, responsiveness.
• 26.2. Test on different browsers (Chrome, Firefox, Safari).
• 26.3. Test on different device sizes using browser developer tools.
• 26.4. Fix any bugs found.
• 26.5. Commit: git commit -m "Completed final testing and bug fixes".
• 27.1. Choose a hosting provider for Next.js (Vercel is highly recommended).
• 27.2. Follow the provider's instructions to connect your Git repository.
• 27.3. Configure environment variables for Convex.
• 27.4. Deploy your Convex project (ensure it's up-to-date: npx convex deploy).
• 27.5. Initiate the build and deployment process.
• 27.6. Access your live app!
• 27.7. Commit: git commit -m "Deployed app to production".

Ready to Start?

Each step is designed to be small and achievable. Tackle them one by one, commit your changes regularly, and watch your app come to life!

© 2025 Core Intuition Engine Development. All rights reserved.