PHASE 0Beginner ~21 min· topic 6 of 7

Topic 0.6

Your Project Folder

In one line

Your dashboard will grow into a small project with a clear folder layout: the page, the data, the code for loading data, one file per chart, shared parts and styles. Here is the final layout, what each part is for, and how it grows from a single index.html.

Think of it like this

A kitchen. Pans go in one cupboard, spices on one shelf, knives in one drawer. Nobody designed it that way to be tidy for its own sake: when you cook fast, you need to find things without thinking. A project folder is a kitchen for code.

Words you'll meet

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

project: All the files that make one app, kept together in one folder.
folder (directory): A named container for files and other folders.
tree: A folder and everything inside it, drawn with each item under its parent, indented one step per level.
module: A JavaScript file that exports functions for other files to import. Each chart file will be one module.
package.json: A small file that names a JavaScript project and lists its commands and the libraries it uses. Created in Phase 4.
public folder: A folder whose files the dev server sends to the browser exactly as they are, such as data files and images.

Step by step

01Read the final tree

The first example prints the final project as a tree, with a one-line note for each part. Each line's indent shows which folder it is in: main.js is inside src/, lumen/ is inside data/, which is inside public/.

02See the tree as a picture

The second example draws the same tree as an SVG: depth (how many folders deep) decides x, and the row number decides y. Folders are drawn as squares, files as circles.

Notice that this is already a chart: two numbers per item (depth and row) became a position. Phase 13 draws real trees from data with D3's hierarchy.

See the tree as a picturediagram

Rendering diagram…

03Know what exists today

Right now only lumen-dashboard/index.html exists (Topic 0.4). The build topic next turns it into the dashboard's first page with three boxes. Don't create the other folders yet: they arrive when they're needed, each with a reason.

04Know how to catch up

Each phase's last topic (build) has a Files section: every project file it adds or changes, shown in full. If something goes wrong in your copy, replace your file with that one and carry on.

Try it yourself

1
Add a folder
In the first example, add { name: "story/", note: "the scrolly story (Phase 17)" } to the end of src/'s children. The printout gains a line under utils/, and utils/ changes from └─ to ├─ because it is no longer the last child.
2
Spread the picture out
In the second example, change both depth * 28 to depth * 40. Each level moves further right. The data didn't change, only the rule that turns depth into x: the same idea as changing a chart's scale.

Code & diagrams

The project tree, printed from data New tab

A function that calls itself for each child (recursion) walks a tree of any depth. Phase 13's tree layouts work the same way.

Console

(nothing was printed)

Expected console output

lumen-dashboard/              the whole project
├─ index.html                 the page (today, the only file)
├─ package.json               name, commands, libraries (Phase 4)
├─ public/                    files served as they are
│  └─ data/                   data files
│     └─ lumen/               the CSV and JSON data (Phase 4)
├─ src/                       your code
│  ├─ main.js                 starts the app
│  ├─ data/                   load and clean data
│  ├─ charts/                 one file per chart
│  ├─ parts/                  axis, tooltip, legend
│  ├─ styles/                 colours and layout
│  └─ utils/                  formatting, config
└─ tests/                     chart tests (Phase 16)

The same tree as a picture New tab

A rect with rx equal to half its width looks like a circle: one shape, two looks.

Preview

Press Run to see the page.

Console

Nothing logged yet.

Expected console output

Items drawn: 14 | deepest level: 3

Break it on purpose

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

Break #1

Remove the last-child check

In the first example, change print(kid, next, i === kids.length - 1) to print(kid, next, false).

terminal

$ Console

── what you'll see ──

lumen-dashboard/ the whole project

├─ index.html the page (today, the only file)

├─ package.json name, commands, libraries (Phase 4)

├─ public/ files served as they are

│ ├─ data/ data files

│ │ ├─ lumen/ the CSV and JSON data (Phase 4)

├─ src/ your code

│ ├─ main.js starts the app

│ ├─ data/ load and clean data

│ ├─ charts/ one file per chart

│ ├─ parts/ axis, tooltip, legend

│ ├─ styles/ colours and layout

│ ├─ utils/ formatting, config

├─ tests/ chart tests (Phase 16)

Myth vs fact

Myth

Folder layout doesn't matter for a small project.

Fact

A dashboard stops being small fast. Setting the layout on day one costs nothing; moving ten charts out of one big file later costs an afternoon and a few bugs.

Myth

There is one correct folder structure.

Fact

Teams use many layouts. What matters is that it is consistent: one place for data loading, one file per chart, shared parts in one folder. This course uses one layout all the way so you can always find things.

Pro corner

Extra depth for experienced readers. New to this? Skip it for now and come back later.

▸
Splitting by role (data, charts, parts) rather than by type (all .js together) keeps change local: a new chart touches charts/ and main.js only. When the React version arrives in Phase 14, the same split maps one-to-one to components, hooks and utilities.
▸
Putting the data URL in config.js is a small form of dependency injection: charts receive data, they never fetch it themselves. That makes them testable with fixed sample data (Topic 16.7) and lets the data move to cloud storage without touching chart code (Topic 4.6).

Remember this

1
The problem this solves: dashboards grow. A single file with ten charts, data loading and styles becomes thousands of lines, and every change risks breaking a chart you weren't looking at. A fixed layout from day one means each chart lives in its own file, data loading lives in one place, and you always know where to look.
2
The final layout. By the end of the course your project looks like the tree in the first example: index.html (the page), package.json (the project's name, commands and libraries, from Phase 4), public/data/lumen/ (the data files), and src/ (your code) with main.js (starts everything), data/ (loading and cleaning), charts/ (one file per chart), parts/ (axes, tooltips, legends shared by charts), styles/ (colours and layout) and utils/ (small helpers such as number formatting and the place the data lives). tests/ arrives in Phase 16.
3
Why one file per chart. Each chart file will export one function, such as drawRidesLine(container, data), that draws one chart into one box. A chart can then be fixed, tested or replaced without touching the others, and the page only decides where each chart goes. Phase 5 gives these functions an update(data) method, so the same chart can redraw with new data.
4
Why the data has its own folder. Data files are not code: they are served as they are, and later they will come from cloud storage instead (Topic 4.6). Keeping them under public/data/lumen/, and keeping the address in one setting (src/utils/config.js), means moving them later changes one line, not every chart.
5
How it grows. Today the whole project is one file: index.html. In Phases 1–3 that file gets bigger. In Topic 4.1 you create the real project with Vite and move the code into src/. Every build topic lists the files it adds or changes, and shows each one in full, so if you fall behind you can copy them and continue. The Files you touch strip at the top of every phase says which ones before you start.
6
Names stay the same. File names, function names and the page's element ids (#rides-line, #stations-bar…) never change during the course, so code from an earlier phase always fits the next one.

Explain it without notes

Why does each chart get its own file?

What goes in public/data/lumen/, and why is its address kept in one setting?

You fell behind in Phase 6. How do you catch up?

Practice

Add a third column to the printed tree: the phase in which each item first appears (use 0 for index.html, 4 for package.json and the data, 16 for tests).

In the second example, colour JavaScript files differently from other files (hint: name.endsWith(".js")).

Trade-offs

↔
Many small files make each piece easy to find and change, but you must keep imports in order. One big file is easy to start but hard to change. This course starts with one file and splits it in Phase 4, when the reasons are clear.

Done when you can

I can name each folder of the final project and what goes in it.
I know that today my project is only index.html.
I know where to find the complete files of every build topic if I fall behind.

Command Palette