Chapter 2

The Blueprint: Project Structure

Explore how files and folders are organized in a real project.

Why Organization Matters

A web application can have hundreds or thousands of files. Without good organization, finding and changing code would be like searching for a specific book in a library with no catalog system. Let's explore how StudyTracker organizes its code.

The Building Analogy

Think of the project like a building

The root folder is the building itself. src/ is the main floor where all the action happens. Inside src, app/ is like the different rooms (each page is a room). components/ is the furniture warehouse — reusable pieces that can go in any room. lib/ is the utility closet — tools and helpers used everywhere.

The Top-Level View

Here's what the StudyTracker project looks like at the top level. Click on folders to explore what's inside:

Project Root
StudyTracker/
├── src/
│   ├── app/          ← Pages & API routes
│   ├── components/   ← Reusable UI pieces
│   └── lib/          ← Utilities & helpers
├── prisma/           ← Database schema
├── package.json      ← Dependencies list
└── next.config.ts    ← Framework settings

The app/ Directory — "Rooms" of Your Website

In Next.js, the folder structure inside app/ directly determines your website's URLs. A file at app/habits/page.tsx automatically becomes the /habits page. This is called file-based routing.

Click folders to explore, click ? for details

Route Groups: Organizing Without Changing URLs

Notice folders wrapped in parentheses like (app) and (auth)? These are route groups — they help organize code without affecting the URL. All pages inside (app)/ share the same sidebar and header. Pages in (auth)/ share a simpler login layout.

Route Group

A folder wrapped in parentheses (e.g., (app)) that groups pages together for shared layouts without adding to the URL path. /habits lives inside (app)/habits/ but the URL is just /habits, not /(app)/habits.

The 9 Modules of StudyTracker

StudyTracker is organized into 9 distinct features, each with its own page, API routes, and components:

1
DashboardOverview of your day
2
HabitsDaily habit tracking with heatmaps
3
TodosTask list with priorities
4
OKR GoalsObjectives & Key Results
5
ProjectsProject management with milestones
6
ContentLearning resource library
7
IdeasIdea capture & categorization
8
Life CompassPersonal mission & values
9
StatsAnalytics across all modules

How a File Becomes a Page

Here's how a simple page file works — the file path determines the URL, and the function returns what the user sees:

src/app/(app)/habits/page.tsx
export default function HabitsPage() {
  const [habits, setHabits] = useState([]);

  useEffect(() => {
    fetch("/api/habits")
      .then(res => res.json())
      .then(data => setHabits(data));
  }, []);

  return (
    <div>
      <h1>My Habits</h1>
      {habits.map(habit => (
        <Card key={habit.id}>{habit.name}</Card>
      ))}
    </div>
  );
}
The most important thing to remember: in Next.js, folders = URLs. If you want to add a new page at /recipes, you create a file at app/recipes/page.tsx.

Test Your Knowledge

Question 1 of 3Score: 0

In Next.js, how do you create a page at the URL /habits?

Previous ChapterNext Chapter