# Find Your Way Around Your Project

Course: Vibe Coding: Build Real Apps with AI Agents — Lesson 2 of 4

Open up the app you just created and make sense of it: the monorepo at a glance, what each folder is for, where your code lives versus the shared UI, and how the Next.js App Router turns folders into pages and URLs.

In the last lesson you ran one command and got a real app at
[https://web.localhost](https://web.localhost). This lesson maps it out. You won't write
code yet.

> **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](https://web.localhost) is a **demo** the template
ships with: buttons, cards, sliders and toggles, the ready-made building blocks
(shadcn/ui) you'll use later. It's a placeholder, not your home page.

Open the project in your editor: `code .` from inside the project folder. Click through
the folders in the sidebar as they come up.

## The project is a monorepo

Your project is a **monorepo**: many related pieces in one repository. Skim the top
level:

```text
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 **agent owns** the rest; you'll rarely touch a
config file by hand.

- **`apps/web`**: your website, the thing running at web.localhost. Almost everything you
  build next lives here.
- **`packages/ui`**: shared UI components, the buttons and cards from the demo. Every app
  in the repo pulls from here.

Later you'll add a Telegram bot and a desktop app, and they all reuse the same
`packages/ui` as the website. Fix a button once and it's fixed everywhere: bot, website,
desktop. Mild overkill for a one-page site, but you won't have to rewire anything when
you grow.

## Inside the web app: the App Router

Open `apps/web/src`, where your website's code lives:

```text
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 the **App Router**. Its one rule:

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

```text
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.

Two filenames are special inside `app/`:

- **`page.tsx`**: what a visitor sees at that URL.
- **`layout.tsx`**: the **frame** around every page: shared fonts, the header and footer
  you'll add later, dark mode. Edit it once, every page changes.

### The line that draws the demo

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

```tsx
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. `<Demo />` is the wall of buttons you saw, and **you'll
replace that line next lesson** with your own content. Don't change anything yet.

### The `@` shortcuts

Those `@` names in the import are **shortcuts** to places in the repo, so files don't
reference each other with long `../../../` paths:

- **`@workspace/ui/...`** is the shared **`packages/ui`** toolbox: the demo, the buttons,
  the cards.
- **`@/...`** is this app's own `src` folder (`apps/web/src`), so `@/components/...`
  belongs to the web app only.

## Where your stuff goes

Keep this table handy:

| Want to change… | Look in… |
| :---- | :---- |
| Home page content | `apps/web/src/app/page.tsx` |
| Add a new page (e.g. `/about`) | `apps/web/src/app/about/page.tsx` |
| The frame around every page (fonts, header) | `apps/web/src/app/layout.tsx` |
| A shared button, card, or input | `packages/ui/src/components/` |
| Colors, fonts, and theme | `packages/ui/src/styles/globals.css` |
| Project settings, linting, deps | root config files *(ask the agent)* |

## Let the agent give you the tour

Start your agent inside the project and try a prompt or two:

```text
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

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

or if you want to learn more:

```text
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 course.

## What's next

Next you'll replace that `<Demo />` with your own content, your name and your title,
built from components you create yourself, and add a second page.

## Links

- Lesson page: https://andrey-markin.com/courses/vibe-coding/tour-your-project
- Course: https://andrey-markin.com/courses/vibe-coding.md
- Next lesson: https://andrey-markin.com/courses/vibe-coding/pages-and-components.md