K
K12worX Education501(c)(3) Public Charity
Jamboree

Codebase Map

Visual guide to the K12worX codebase structure. Use this as a reference to navigate the project and understand where everything lives.

Project Overview

k12worx-jamboree/
├── website/           → Next.js website (main app)
├── docs/             → Pilot program documentation
└── README.md         → Project overview

You'll work primarily in website/ - that's where the Next.js application lives.

Website Folder Structure

website/
├── app/              → Pages and routes (Next.js 15 App Router)
├── components/       → Reusable React components
├── docs/            → Learning guide markdown files
├── public/          → Static files (images, icons)
├── lib/             → Utility functions and helpers
├── types/           → TypeScript type definitions
├── styles/          → Global styles (if any)
├── tailwind.config.ts  → Tailwind CSS configuration
├── next.config.ts      → Next.js configuration
├── package.json        → Dependencies and scripts
└── tsconfig.json       → TypeScript configuration

The app/ Directory

This is where pages live. Folder structure = URL structure.

Current Pages

app/
├── page.tsx                    → / (Homepage)
├── layout.tsx                  → Root layout (wraps all pages)
│
├── about/
│   └── page.tsx               → /about
│
├── contact/
│   └── page.tsx               → /contact
│
├── get-involved/
│   ├── page.tsx               → /get-involved
│   └── student-leaders/
│       └── page.tsx           → /get-involved/student-leaders
│
├── impact/
│   └── page.tsx               → /impact
│
├── launching/
│   └── page.tsx               → /launching
│
├── learn/
│   ├── page.tsx               → /learn
│   └── [...slug]/
│       └── page.tsx           → /learn/* (learning guide pages)
│
├── model/
│   └── page.tsx               → /model
│
├── programs/
│   └── page.tsx               → /programs
│
├── technology/
│   └── page.tsx               → /technology
│
├── updates/
│   └── page.tsx               → /updates
│
└── api/                        → API routes
    └── contact/
        └── route.ts           → POST /api/contact

Key Files in app/

page.tsx

  • The actual page content
  • Default export is the component
  • Example: app/about/page.tsx → renders at /about

layout.tsx

  • Wraps pages with common structure
  • app/layout.tsx wraps ALL pages
  • Can have nested layouts in subfolders

route.ts (in api/ folders)

  • API endpoints
  • Handle GET, POST, etc.
  • Example: app/api/contact/route.ts

The components/ Directory

Reusable UI components. Organized by purpose.

components/
├── layout/               → Page structure components
│   ├── Header.tsx           → Site header with logo
│   ├── Navigation.tsx       → Main navigation menu
│   ├── Footer.tsx           → Site footer
│   ├── DefaultLayout.tsx    → Standard page wrapper
│   ├── LandingLayout.tsx    → Homepage-style layout
│   ├── ArticleLayout.tsx    → Blog/article layout
│   └── GridLayout.tsx       → Grid-based layout
│
├── content/              → Content-specific components
│   ├── ActivityChronicle.tsx    → Timeline of activities
│   ├── ActivityEntry.tsx        → Single timeline entry
│   ├── CommitteeMemberCard.tsx  → Team member cards
│   ├── ContactForm.tsx          → Contact form
│   ├── FeaturedPhoto.tsx        → Photo display
│   ├── ImageModal.tsx           → Image popup
│   └── MilestoneCard.tsx        → Milestone displays
│
├── docs/                 → Learning guide components
│   ├── MarkdownContent.tsx      → Renders markdown
│   ├── Breadcrumbs.tsx          → Navigation breadcrumbs
│   ├── TableOfContents.tsx      → Auto-generated TOC
│   └── NavigationButtons.tsx    → Prev/Next navigation
│
└── AccessGate.tsx        → Access control (launching stage)

Component Usage Patterns

Layout components (components/layout/)

  • Wrap page content
  • Provide consistent structure
  • Used in most pages

Content components (components/content/)

  • Specific to certain pages
  • Reusable across similar contexts
  • Self-contained

Docs components (components/docs/)

  • Specific to learning guide
  • Markdown rendering
  • Navigation helpers

The docs/ Directory

Learning guide markdown files. What you're reading now!

docs/
└── learning-guide/
    ├── README.md                    → Guide overview
    │
    ├── 00-prerequisites/
    │   ├── README.md
    │   ├── required-software.md
    │   ├── creating-github-account.md
    │   ├── installing-vscode.md
    │   ├── installing-nodejs.md
    │   └── joining-the-team.md
    │
    ├── 01-understanding-basics/
    │   ├── README.md
    │   ├── what-is-code.md
    │   ├── files-and-folders.md
    │   ├── html-basics.md
    │   ├── css-basics.md
    │   ├── javascript-basics.md
    │   └── how-websites-work.md
    │
    ├── 02-getting-started/
    │   ├── README.md
    │   ├── cloning-the-repo.md
    │   ├── opening-in-vscode.md
    │   ├── installing-dependencies.md
    │   ├── running-dev-server.md
    │   └── your-first-change.md
    │
    ├── 03-understanding-structure/
    │   ├── README.md
    │   ├── nextjs-basics.md
    │   ├── app-folder-structure.md
    │   ├── components-explained.md
    │   ├── routing-system.md
    │   └── where-to-find-things.md
    │
    ├── 04-reading-code/
    │   ├── README.md
    │   ├── reading-homepage.md
    │   ├── reading-header.md
    │   ├── reading-navigation.md
    │   └── understanding-props.md
    │
    ├── 05-styling-basics/
    │   ├── README.md
    │   ├── tailwind-classes.md
    │   ├── responsive-design.md
    │   └── customizing-colors.md
    │
    ├── 06-making-changes/
    │   ├── README.md
    │   ├── changing-text-content.md
    │   ├── adding-new-links.md
    │   ├── modifying-styles.md
    │   └── testing-your-changes.md
    │
    ├── 07-git-basics/
    │   ├── README.md
    │   ├── git-workflow.md
    │   ├── creating-branches.md
    │   ├── making-commits.md
    │   └── understanding-pull-requests.md
    │
    ├── 08-advanced-topics/
    │   ├── README.md
    │   ├── creating-new-pages.md
    │   ├── building-components.md
    │   ├── working-with-forms.md
    │   └── understanding-typescript-types.md
    │
    ├── 09-troubleshooting/
    │   ├── README.md
    │   ├── common-errors.md
    │   ├── debugging-tips.md
    │   └── getting-help.md
    │
    └── 10-reference/
        ├── README.md
        ├── glossary.md
        ├── useful-commands.md
        ├── external-resources.md
        └── codebase-map.md         → You are here!

The public/ Directory

Static assets. Files here are served as-is.

public/
├── icons/               → Favicons, app icons
│   ├── favicon.ico
│   └── ...
│
└── images/              → Photos, graphics
    ├── committee/       → Team member photos
    │   ├── photo1.jpg
    │   └── ...
    │
    └── partners/        → Partner logos
        └── ...

Accessing Public Files

In code, reference from root:

// In a component
<img src="/images/logo.png" alt="Logo" />

// Not: /public/images/logo.png
// Just: /images/logo.png

Configuration Files

package.json

Defines the project and its dependencies.

{
  "name": "website",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "15.0.0",
    "react": "^18.2.0",
    // ... more packages
  }
}

Key sections:

  • scripts: Commands you can run (npm run dev)
  • dependencies: Packages the app needs
  • devDependencies: Packages only needed for development

next.config.ts

Next.js configuration.

const nextConfig = {
  output: 'export', // Static site generation
  images: {
    unoptimized: true, // For static export
  },
};

export default nextConfig;

Common settings:

  • output: Build mode
  • images: Image optimization
  • redirects: URL redirects
  • rewrites: URL rewrites

tailwind.config.ts

Tailwind CSS configuration.

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        // Custom colors
      },
    },
  },
  plugins: [],
};

Key sections:

  • content: Where to look for class names
  • theme.extend: Custom colors, fonts, etc.
  • plugins: Tailwind plugins

tsconfig.json

TypeScript configuration.

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "preserve",
    "paths": {
      "@/*": ["./*"]  // Allows @/components imports
    }
  }
}

Key settings:

  • paths: Import aliases (@/ = project root)
  • strict: Type checking strictness
  • jsx: How to handle JSX

Important Files by Task

Want to change homepage content?

→ app/page.tsx

Want to add a new page?

→ Create app/your-page/page.tsx

Want to modify navigation menu?

→ components/layout/Navigation.tsx

Want to change header/footer?

→ components/layout/Header.tsx or Footer.tsx

Want to add a new component?

→ Create in components/ (choose appropriate subfolder)

Want to change site-wide styles?

→ tailwind.config.ts (colors, fonts) → app/globals.css (custom CSS)

Want to add images?

→ Put in public/images/ → Reference as /images/filename.jpg

Want to modify learning guide?

→ Edit files in docs/learning-guide/

Having build errors?

→ Check package.json (dependencies) → Check console output → See Common Errors

File Naming Conventions

Next.js Special Files

These file names have special meaning in Next.js:

  • page.tsx - Defines a route
  • layout.tsx - Wraps routes in a folder
  • loading.tsx - Loading state
  • error.tsx - Error state
  • not-found.tsx - 404 page
  • route.ts - API endpoint

Component Files

Use PascalCase:

✅ Header.tsx
✅ ContactForm.tsx
✅ NavigationMenu.tsx

❌ header.tsx
❌ contactform.tsx

Other Files

Use kebab-case:

✅ tailwind.config.ts
✅ next.config.ts
✅ common-errors.md

❌ tailwindConfig.ts
❌ CommonErrors.md

Understanding Imports

Absolute Imports (Preferred)

Using @/ alias:

import Header from '@/components/layout/Header';
import { formatDate } from '@/lib/utils';

@/ always refers to project root (where package.json is).

Relative Imports

Using ./ and ../:

// Same folder
import Button from './Button';

// Parent folder
import Layout from '../layout/DefaultLayout';

// Two levels up
import utils from '../../lib/utils';

When to use:

  • Components in same folder
  • Importing from nearby files

When to avoid:

  • Deep nesting (../../../../utils)
  • Use @/ instead

Common Patterns

Creating a New Page

  1. Create folder and file:

    app/my-page/page.tsx

  2. Add content:

    export default function MyPage() {
  return <div>My Page Content</div>;
}

  3. Add to navigation (if needed):

    // In components/layout/Navigation.tsx
const navItems = [
  // ... existing items
  { name: "My Page", href: "/my-page" },
];

Creating a Component

  1. Create file in appropriate folder:

    components/content/MyComponent.tsx

  2. Define component:

    interface MyComponentProps {
  title: string;
  description?: string;
}

export default function MyComponent({ title, description }: MyComponentProps) {
  return (
    <div>
      <h2>{title}</h2>
      {description && <p>{description}</p>}
    </div>
  );
}

  3. Use in a page:

    import MyComponent from '@/components/content/MyComponent';

<MyComponent title="Hello" description="World" />

Quick Navigation Guide

I want to...

Change homepage:

app/page.tsx

Add a page:

app/new-page/page.tsx

Modify navigation:

components/layout/Navigation.tsx

Change header:

components/layout/Header.tsx

Add an image:

public/images/my-image.jpg
→ Use as: /images/my-image.jpg

Add a reusable component:

components/content/MyComponent.tsx

Change colors:

tailwind.config.ts

Add a dependency:

npm install package-name

View learning guide:

docs/learning-guide/

Build Output

.next/ Directory

Generated by Next.js during build. Don't edit!

  • Created by: npm run build
  • Contains: Optimized production code
  • Should be in .gitignore
  • Delete and rebuild if issues: rm -rf .next && npm run build

out/ Directory

Static export output (when using output: 'export').

  • Created by: npm run build
  • Contains: Fully static HTML/CSS/JS
  • Can be deployed to any static host
  • This is what goes live

Version Control

.gitignore

Files Git should NOT track:

node_modules/     # Dependencies (reinstall with npm install)
.next/            # Build output
out/              # Static export
.env.local        # Environment variables (secrets)
.DS_Store         # Mac system files

Always committed:

  • Source code (app/, components/, etc.)
  • Configuration files
  • package.json and package-lock.json
  • Documentation

Quick Reference

Main folders:

app/         → Pages (URL routes)
components/  → Reusable UI
docs/        → Learning guide
public/      → Static files
lib/         → Utilities

Key files:

app/page.tsx              → Homepage
app/layout.tsx            → Root layout
package.json              → Dependencies
tailwind.config.ts        → Styling config
next.config.ts            → Build config

Import paths:

@/components/...   → components/...
@/lib/...          → lib/...
./Component        → Same folder
../Component       → Parent folder

File types:

.tsx   → TypeScript + React
.ts    → TypeScript
.css   → Styles
.md    → Markdown

Next Steps

You now have a complete map of the codebase! Use this reference whenever you need to:

  • Find where a file lives
  • Understand the folder structure
  • Know where to create new files
  • Navigate the project efficiently

Ready to build? Go back to the guide: