The previous module closed out the technical tour and ended with a promise: build CicloUrbano end to end, from scratch, with Vite and React Router. This lesson is the first step, and it's the one most people skip: before writing a single line of JSX you need to know what you're building, for whom, with what data, and with what technical decisions. A project that starts with npm create vite without having answered those questions ends up, without exception, being refactored halfway through.

You're going to do three things, in this order. First, define the product: the scope in one sentence, the two user personas, the stories with their acceptance criteria, and — just as important as the rest — the explicit list of what doesn't make it into the first version. Second, pin down the architecture decisions in a record that justifies every choice and names the alternative that was rejected, so that three months from now nobody has to reconstruct the reasoning. And third, set up the real scaffolding: Vite, dependencies, scripts, linter, formatter, environment variables, folder structure, a seeded json-server, and a first commit that already runs.

By the end you'll have a repository that clones, installs, and runs, with the development API responding and not a single screen written yet. The screens are the next lesson.

1. The product in one sentence
2. User personas and their goals
3. User stories and acceptance criteria
4. What's out of scope for the first version, and why
5. The final data model
6. The complete initial db.json
7. Screen map and route tree
8. The architecture decision record
9. Creating the project with Vite
10. Dependencies: what gets installed and why
11. The complete package.json
12. Code quality: ESLint, Prettier, and .editorconfig
13. Environment variables with import.meta.env
14. Folder structure: by type or by feature
15. The development API: json-server up and running
16. Team conventions
17. The work plan: vertical slices
18. The first commit

If you can't describe what you're building in one sentence, you don't yet know what you're building. This project's sentence:

CicloUrbano is a private web application that lets a customer book bikes from a station-based urban network, and lets an operator maintain the status of the fleet.

That sentence carries more information than it looks like:

The word "private" is the one that decides the rendering architecture, and it does so before any tool gets discussed. We'll come back to it in section 8.

Two personas, not one more. A product with five profiles in its first version doesn't get any of them right.

This table produces two design consequences that aren't up for discussion afterward:

• The home screen is the catalogue, not a dashboard. The customer is the one who opens the app most, and does so in a hurry.
• The workshop is a separate screen with role-based access, not a hidden mode of the catalogue. Mixing both uses into one screen would force hiding controls by permission on every card, which is exactly the kind of complexity you pay for over years.

A user story has a fixed shape — as an X I want Y so that Z — and it's only useful if it carries testable acceptance criteria. "The catalogue should work well" isn't a criterion; "filtering by electric only shows bikes of type electrica" is. In 11-04 each of these criteria turns into a test, which is why they're written this way starting today.

The distinction isn't cosmetic: if the deadline tightens, you cut at D1-D4 without touching H1-H8. Having that line drawn before you start is what keeps a project from shipping ten half-finished things instead of eight finished ones.

This list matters as much as the previous one, and it's worth writing down and sharing, because whatever isn't written down eventually gets requested halfway through the project.

Notice that last row. Deciding something is out of scope isn't deciding it will never happen: it's deciding it doesn't compete for this version's time, while also noting down how it would be done if the moment comes.

Four entities. You know them from the whole course; here they're pinned down along with their relationships.

Three modeling decisions worth understanding before you start coding:

1. Relationships are stored by identifier, never by nesting the whole object. A booking stores bicicletaId, not a copy of the bike. If it nested the object, the booking's price would freeze at the moment of creation, and any change to the bike would leave out-of-sync copies scattered across the database. It's the same normalization applied to Redux state in 07-04, for the same reason.
2. Status is a string from a closed set, not a boolean. disponible | alquilada | mantenimiento allows for a fourth status the day one is needed; disponible: true/false forces you to add another boolean and reason about impossible combinations.
3. The booking field is called user and holds an identifier. It's a naming inconsistency with bicicletaId, and it's kept because that's how it was fixed throughout the course: changing it now would break validateBooking, the tests, and the MSW handlers. It's noted as minor technical debt in the record, which is exactly what you do in a real project with a harmless, already widespread inconsistency.

This file is the development database and, at the same time, the seed that 11-04 will restore before every end-to-end test. It goes in the root of the repository.

The dataset is chosen so that every status and every edge case has at least one representative, which is the property any development dataset should have:

That second-to-last case is the one most often forgotten, and the one that produces the most bugs: if you never see the empty list in development, you don't design it, and the user opening the app for the first time hits a blank gap.

The routes were fixed back in module 6. Here we check that each one serves a story, and that no story is left without a screen.

And the coverage table, which is what gets reviewed to spot gaps:

One detail that changes from module 6: /reservas now sits inside the protected branch. Back then it was left public so as not to complicate the examples; in the real project, viewing bookings requires a session, because they're personal data. It's exactly the kind of adjustment that surfaces while building this table, which is why you build the table.

This is the most valuable document in the lesson. Each row records what gets decided, why, and what gets rejected. It's saved in the repository as DECISIONS.md and updated whenever something changes; a row is never deleted — a new one is added with its date instead.

And the state assignment, which is the literal application of 07-01's taxonomy to this project:

With the record signed off, the scaffolding is mechanical.

What each line did:

• npm create vite@latest downloads and runs the official generator. The -- separates npm's own arguments from the generator's; without it, npm would try to interpret --template as its own.
• --template react picks the React template with JavaScript. react-ts exists for TypeScript and react-swc for using SWC instead of Babel; with React 19 and the official plugin, the speed difference on a project this size is irrelevant.
• npm run dev starts the development server at http://localhost:5173.

Check the React version before moving on, because the project assumes React 19:

Nothing gets installed "just because." Every package answers to a row in the record.

The distinction between dependencies and devDependencies isn't bureaucracy: whatever is in dependencies can end up in the bundle the user downloads. Putting json-server or Cypress there wouldn't break Vite's build, but it would bloat every production install and give a false signal about what the application actually needs to run.

The scripts deserve a comment, because they're the project's interface for anyone new who shows up:

The --max-warnings 0 on lint is deliberate: a warning that breaks nothing piles up until there are a hundred and twenty of them and nobody looks anymore. Either they matter and fail the build, or the rule gets disabled.

Vite generates a basic eslint.config.js. Here's the project's version, with the two additions the record calls for: accessibility and hooks rules.

Three points worth understanding, not copying:

• react-hooks/exhaustive-deps as error, not warn. It's the most debated setting in any React configuration, and here it's a deliberate choice: 05-02 showed that a missing dependency produces stale data that doesn't fail in development but does in production. As a warning, it gets ignored; as an error, it forces you to fix it or justify the exception with an eslint-disable-next-line comment that stays visible in code review.
• jsx-a11y in recommended mode. It catches, right in the editor, the image with no alt, the onClick on a div with no role or keyboard handling, and the label with no associated control. It doesn't replace the manual review from 03-06, but it removes 80% of the usual mistakes before they exist.
• prettier goes last in the array. eslint-config-prettier doesn't add rules: it disables the ESLint ones that collide with formatting. If it were placed earlier, the rules that follow would turn them back on, and you'd have the linter and the formatter fighting each other on every save.

.editorconfig is what avoids the classic "the whole file shows up modified in the diff" when someone works on Windows: it fixes line endings and indentation at the editor level, before Prettier ever steps in.

The API's URL can't be hand-written into fifteen files. Vite exposes environment variables through import.meta.env, with one strict rule: only the ones that start with VITE_ reach the client code.

Why a config.js module instead of reading import.meta.env wherever it's needed:

1. A single source of truth. The day the variable's name changes, you touch one file.
2. Default values in one place, with ??, so that cloning the repository and forgetting the .env doesn't break startup.
3. It can be swapped out in tests with a vi.mock of your own module; scattered import.meta.env calls can't be.

And the warning that 11-05 will repeat in full: import.meta.env is text that gets embedded in the JavaScript the browser downloads. Anyone can read it in two clicks. A private API key, a password, or an admin token never goes there, not even "just temporarily while we test."

There are two schools of thought, and both are right in their context:

CicloUrbano adopts a hybrid, which is what most real projects of this size do: by type for what's shared, by feature for domain state. That last part was already decided back in 07-05.

Two placement rules that avoid most arguments:

• A test file lives next to the code it tests (BikeCard.jsx and BikeCard.test.jsx in the same folder). Only the testing infrastructure lives in src/tests/. That way, deleting a component takes its test with it.
• A component moves up to components/ when a second screen uses it, not before. Until then, it lives next to its page. Generalizing from a single use case produces the wrong abstractions.

Mandatory check before moving on. If this doesn't respond, no screen in 11-03 will work, and you'll waste an hour looking for the bug in React:

What json-server gives you out of the box, and what the project is going to use:

And what it doesn't give you, and you need to keep in mind from now on: it validates nothing, authenticates nobody, and checks no permissions. A PATCH from the browser console changes any bike's status with no session at all. That's acceptable in development, and it's why 11-05 insists that real authorization is always checked on the server.

Written down in README.md, because a convention that only lives in the head of whoever invented it isn't a convention.

Names

Exports: export default for components and pages; named exports for hooks, utilities, slices, and selectors. Mixing the two criteria within the same file type is what produces inconsistent imports.

Import order, always the same, with a blank line between groups:

Commit messages, in conventional format, in English and in the imperative:

The prefix isn't decoration: it lets you generate the changelog automatically and, above all, it forces a commit to do exactly one thing. If you're torn between feat and fix, the commit probably contains two changes and needs to be split.

Here's the methodology decision that most influences how the project feels while it's being built.

Vertical is the choice, with an honest caveat: this module is organized by layer — interface, state, testing, deployment — because explaining requires grouping concepts, while building requires delivering value early. It's an important distinction worth keeping straight: the order of the book isn't the order of the workshop.

Even so, within each lesson the work happens by complete stories. And if you were building this project on a real team, the order would be this:

And the order of the stories, prioritized by risk first:

1. H4 (sign-in) before anything else: it's the gateway to everything else and touches session, form, redirect, and persistence. If something's going to go wrong in the architecture, it goes wrong here.
2. H1 + H2 (catalogue and filter): the most-visited screen, and the one that validates the data layer.
3. H5 (booking): the money path. Touches mutation, validation, invalidation, and navigation.
4. H6 (my bookings and cancel): reuses almost everything before it.
5. H3, H8 (detail page and stations): pure reads, low risk.
6. H7 (workshop): the role gets tested with everything else already standing.
7. D1-D4 if there's time left.

The rule governing the list: whatever can sink the project goes first. Leaving sign-in for last is the classic mistake, because it's exactly the feature that cuts across every layer and forces you to redo what was already considered done.

An initial commit has to satisfy one condition: whoever clones it can start it up.

And the README.md that ships with it, which is the first thing anyone reads:

npm install cp .env.example .env npm run dev:all # Vite on :5173 and json-server on :3001

The checklist before calling the scaffolding done:

• [ ] npm install works on a clean clone
• [ ] npm run dev serves the application on 5173
• [ ] npm run api responds on 3001 with all four resources
• [ ] npm run lint finishes with no errors or warnings
• [ ] .env is ignored and .env.example is versioned
• [ ] DECISIONS.md has all ten rows of the record
• [ ] README.md lets you start up without asking anyone anything

• Starting with the code and planning on the fly. This is the underlying mistake of the whole lesson. Without stories with acceptance criteria you don't know when you're done, and without a decision record, every technical discussion repeats itself every two weeks. Half a day of planning saves weeks.
• Stories with no testable criteria. "The catalogue should be fast" can't be verified or turned into a test. "The catalogue shows the skeleton while loading and the list as soon as the data arrives" can.
• Not writing down what's out of scope. Scope that isn't explicitly denied is assumed included. The table in section 4 is what protects the delivery.
• Nesting objects in the data model. Storing the whole bike inside the booking feels convenient on day one and produces out-of-sync data on day two. Identifiers, always.
• A development dataset with no edge cases. If every bike is available and every user has bookings, you'll never see the empty state or the disabled button, and they'll reach production broken.
• Putting development tools in dependencies. Cypress and json-server in production are a symptom that nobody has looked at package.json since it was generated.
• Leaving exhaustive-deps as a warning. Over time, dozens pile up and nobody reads them anymore. As an error, it gets resolved or justified with a visible comment.
• Putting eslint-config-prettier anywhere but last. It stops having any effect, and you end up with the linter and the formatter fighting on every save.
• Secrets in VITE_ variables. Everything that starts with VITE_ travels to the browser in plain text. There's no exception, not even "just while we test."
• Tip: create DECISIONS.md from day one and add a row every time you discuss a technical choice. The value isn't in the document, it's in never having the same conversation twice.
• Tip: verify the API with curl before writing the first fetch. Ruling out half the system in thirty seconds saves incredibly long debugging sessions.

Exercise 1. The client requests a new story: "as a customer I want to receive a notice 10 minutes before my booking ends." Write it using the format from section 3, with testable acceptance criteria. Then decide whether it's a must-have or a nice-to-have, and whether it makes it into the first version, justifying your answer with the scope from section 1 and the table from section 4. If you decide to leave it out, write the corresponding row.

Exercise 2. The team proposes adding an Incidencia (Incident) entity for the incidents tab of /estaciones/:estacionId, holding the details of a reported fault. Define its fields and relationships, add it to the entity-relationship diagram and to db.json with two example records consistent with the canon, and explain which new resources would appear in json-server. Also state which TanStack Query key would correspond to it, following the project's factory.

Exercise 3. A teammate proposes three changes to the record: (a) using BrowserRouter with <Routes> because "it's simpler," (b) storing the bike list in Redux "to keep everything in one place," and (c) putting a map service key in VITE_CLAVE_MAPAS to use it from the client. Answer each one with the corresponding technical argument and say which row of the record covers it. For the third, also explain what it would take to use that service without exposing the key.

Solution 1.

Classification: nice-to-have (D5), out of the first version. The three arguments:

1. It doesn't block either persona's main goal. Ana can book and use the bike without the notice; Marc doesn't need it at all.
2. The genuinely useful notice is the one that arrives with the app closed, and that means push notifications, which are explicitly out of scope because they require a server, permissions, and a service worker. A notice that only shows with the tab open solves a small fraction of the real problem and can create a false sense of coverage.
3. It requires a global timer that re-evaluates every minute and a source of truth for the current time, which complicates testing (you have to freeze the clock) for a marginal benefit in this version.

Row for the table in section 4:

And the honest note: once the real API arrives, this story is promoted to must-have, because the business penalizes late returns and warning the customer is cheaper than charging surcharges.

Solution 2.

Fields and relationships. An incident belongs to one bike (which in turn is at a station) and is reported by one user:

Records for db.json, consistent with the canon — bici-003 is in maintenance, so it's the natural candidate to have an open incident, and bici-002 can have one already resolved:

Important modeling decision: the incident is associated with the bike, not the station, even though the tab that shows it belongs to a station. The reason is that a fault travels with the bike: if bici-003 moves to est-03, its history has to go with it. A station's incidents tab is then obtained by deriving: that station's bikes, and those bikes' incidents. Modeling the relationship the other way around would force rewriting the stationId of every incident on every transfer.

Resources that show up in json-server:

And the query key, making use of the fact that the project's factory already anticipated it:

The hierarchy matters: invalidating ['stations', 'est-02'] also invalidates ['stations', 'est-02', 'incidents'], because TanStack Query compares keys by prefix. That's exactly the behavior you want when resolving an incident.

Solution 3.

(a) BrowserRouter with <Routes>. Covered by row A2. It's true that it's simpler to write, but the project needs three things that mode doesn't give you:

• An errorElement per branch: without it, a failure loading a bike's detail page brings down the whole application instead of leaving the header and menu standing. It's the difference between a blank screen and a contained error.
• Route-level lazy with the router managing the loading, which is what makes the code splitting from 08-04 possible without wrapping every screen by hand.
• The data API (useNavigation, useRouteError, handle for breadcrumbs), already used in Breadcrumbs.

And the decisive argument: migrating later costs more than starting right, because it means rewriting the whole route tree once there are already screens built on top of it.

(b) The bike list in Redux. Covered by A3 and by the state assignment table. "Keeping everything in one place" sounds tidy, but it mixes two things of a different nature: bikes are server state, a local copy of data that lives on another machine and can change without the application knowing. Putting them in Redux forces you to write, and maintain, all of this by hand:

It's exactly the work 07-06 showed isn't worth rewriting. Redux keeps what's genuinely its own: session, search term, and sort order.

(c) The map service key in VITE_CLAVE_MAPAS. This is the most serious of the three. Everything that starts with VITE_ gets substituted literally into the code at build time and ends up in a file in dist/ that anyone can open:

No amount of obfuscation fixes this: the browser has to be able to read it to use it, so the user can too. The consequences are usage billed to your account and, depending on the service, access to data that shouldn't be exposed.

What to do instead, in order of preference:

1. Make the request to the service leave from the server. The client calls your API, your API calls the service with the key and returns the result. The key never leaves the machine.
2. If the service is meant for the client — many map providers offer public keys — use that kind of key and restrict it in the provider's dashboard by origin domain, quota, and minimum permissions. It's still visible, but it only works from your domain and with a spending cap.
3. Never use a key with write or billing permissions from the client, under any circumstances.

And since the exercise starts from a story that's out of scope — the geographic map — the complete answer includes pointing that out: there's no need to solve the key problem yet, because the feature isn't part of this version.

This lesson has turned an idea into a project ready to start building, and it's done so in the right order: first the product, then the decisions, and only at the end the tools.

From the product, the essentials are fixed: CicloUrbano in one sentence that already decides the architecture by declaring itself private, two user personas with different goals and contexts that justify why the home screen is the catalogue and the workshop is a separate screen, eight must-have stories and four nice-to-haves with testable acceptance criteria — which in 11-04 literally become tests — and an explicit list of what's out of scope with its reasoning, which is what protects the delivery when someone proposes adding a map halfway through.

From the domain, what remains is the final model with its four entities and three rules honored without exception: relationships by identifier and never nested objects, statuses as a string from a closed set instead of booleans, and inherited inconsistencies noted as debt instead of fixed at the wrong time. db.json isn't a pile of filler data: every status, every edge case, and the empty state each have their representative, because what you don't see in development doesn't get designed.

From the technical direction, what remains is the decision record, ten rows with their justification and their rejected alternative: Vite instead of Next.js because the application is private and interactive; React Router in data mode for errorElement, lazy, and the data API; TanStack Query for the server and Redux Toolkit for the client, with context for theme and notices and the URL for the filter; CSS Modules; the Vitest, Testing Library, MSW, and Cypress quartet; and JavaScript now with the door open to TypeScript. Alongside the record, the state assignment table that answers in advance the question that comes up most often in a React project: where does this piece of data live?

And from the scaffolding, what remains is a working repository: Vite with React 19, dependencies chosen one by one and cleanly split between production and development, a package.json with fourteen scripts that make up the project's interface, ESLint with jsx-a11y and exhaustive-deps raised to an error, Prettier last in the chain, .editorconfig, .gitignore, environment variables centralized in config.js with a versioned .env.example and no secrets, a hybrid folder structure — by type for what's shared, by feature for domain state — json-server seeded and verified with curl, the team's conventions written down in README.md, and a work plan organized in vertical slices that tackles the highest-risk work first.