Find Your Way Around Your Project

In the last lesson you ran one command and got a real app on screen at https://web.localhost. It works — but right now it's a black box. This lesson opens the box.

You won't memorize any of this, and you won't write code yet. The agent does the navigating. This lesson is the map — so when you say "change the home page" the agent (and you) both know exactly where that is. Skim it once now; come back when you need it.

The whole point in one line: once you can name the right folder, your prompts go from "how do I make a page in Next.js?" to "edit the home page" — and the second kind works far more reliably.

What you're actually looking at

The page at https://web.localhost is a demo the template ships with. It's a wall of buttons, cards, sliders, and toggles — a showcase of the ready-made building blocks (shadcn/ui) you'll use later, all on one screen so you can see they work.

It's not your home page yet — it's a placeholder. By the end of this lesson you'll know the exact file that draws it, and in the next lesson you'll replace it with your own content.

Open the project in your editor if it isn't already (code . from inside the project folder), and follow along by clicking through the folders in VS Code's left sidebar as they come up.

The project is a monorepo

Your project isn't one app in one folder — it's a monorepo: many related pieces living in one repository. Here's the top level (skim it, don't study it):

my-website/
├─ apps/
│  └─ web/                  # your website — the thing at web.localhost
├─ packages/
│  ├─ ui/                   # shared UI components (buttons, cards…), reused everywhere
│  ├─ api/                  # your backend/API (you'll meet this in later lessons)
│  ├─ env/                  # environment variables, kept typed and tidy
│  └─ typescript-config/    # shared TypeScript settings
├─ scripts/                 # one-off maintenance scripts (e.g. upgrading deps)
├─ package.json             # root settings + the list of workspaces above
├─ biome.jsonc              # lint & format rules
└─ turbo.json               # the task runner that ties it all together

Two folders matter to you right now; the rest the agent owns — you'll rarely touch config files by hand, and when they need changing, you ask the agent.

• apps/web — your website. This is what's running at web.localhost. Almost everything you build in the next few lessons lives here.
• packages/ui — a shared toolbox of UI components (the buttons and cards from the demo). Every app in the repo pulls from this one place.

Why split it up like this? Later in the course you'll add a Telegram bot and a desktop app. They'll all reuse the same packages/ui. Fix a button once, and it's fixed everywhere — bot, website, desktop. One repo, one source of truth, no copy-paste drift. For a one-page site it's mild overkill; the template sets it up now so you don't have to rewire anything when you grow.

Inside the web app: the App Router

Open apps/web/src — this is where your website's code lives. Two folders inside it:

apps/web/
└─ src/
   ├─ app/                  # your pages live here (the "App Router")
   │  ├─ page.tsx           #   the home page        →  shows at  /
   │  └─ layout.tsx         #   the frame around every page
   └─ components/           # pieces specific to this app
      └─ providers.tsx      #   app-wide setup (theme, etc.)

Next.js uses something called the App Router, and its one rule is the thing worth remembering:

Folders inside app/ become pages, and the folder path becomes the URL.

app/page.tsx            →   /            (your home page)
app/about/page.tsx      →   /about
app/blog/page.tsx       →   /blog

To add an About page, you (or the agent) make a folder app/about/ with a page.tsx inside it — and /about exists. No routing setup, no list of pages to register. The folder structure is the site map. You'll do exactly this in the next lesson.

Two filenames carry special meaning inside app/:

• page.tsx — the page itself. What a visitor sees at that URL.
• layout.tsx — the frame wrapped around every page: shared fonts, the header/footer you'll add later, dark-mode setup. Edit it once, every page changes.

The line that draws the demo

Open apps/web/src/app/page.tsx. It's tiny:

import { Demo } from "@workspace/ui/components/demo";

const Page = () => (
  <div className="flex min-h-svh items-center justify-center">
    <Demo />
  </div>
);

export default Page;

That's the whole home page. It pulls in Demo and drops it on screen — <Demo /> is the wall of buttons you saw. That <Demo /> line is what you'll replace next lesson with your own content. Don't change anything yet; just notice how little there is.

One thing worth knowing: the @ shortcuts

See @workspace/ui/components/demo in that import? Those @ names are shortcuts to places in the repo, so files don't reference each other with long ../../../ paths. Two you'll see constantly:

• @workspace/ui/... → the shared packages/ui toolbox. The demo, buttons, and cards all come from here.
• @/... → this app's own src folder (apps/web/src). So @/components/... means "a component that belongs to the web app specifically."

Quick read: @workspace/... = shared across the whole repo; @/... = just this app. That distinction tells you, at a glance, whether something is reused everywhere or local to one app.

Where your stuff goes

Here's the cheat sheet — the "if I want to change X, look in Y" table. This is the part to keep handy:

You don't have to recall these from memory — the agent knows them too. The win is that you can now aim the agent: "edit the home page" lands on page.tsx directly, instead of a vague back-and-forth about how Next.js works.

Let the agent give you the tour

You don't have to read code to understand it — that's what the agent is for. Start your agent inside the project and try a prompt or two:

Walk me through this project like I'm new to it. What's in apps/web vs packages/ui,
and which file draws the page I see at web.localhost?

and

What does apps/web/src/app/layout.tsx do, in plain English?

or if you want to learn more:

Explain in simple language how nextjs 16 app router works.

Asking the agent to explain your code — not code in the abstract — is one of the most useful habits in this whole course. Use it any time a file looks like noise.

What's next

You can read the map. Next you'll change it: replace that <Demo /> with your own content — your name, your title — built from components you create yourself, and add a second page while you're at it.