Technical courses usually fail for the same reason: each lesson teaches an isolated API with a toy example, and by the end you know how to write twenty fragments you have never seen fit together. This course works the other way round. Everything you learn from here on will build a single real application, module by module, until it reaches production as an API.

That application is Escena Viva. You have already seen its data in the previous lessons; now we are going to formalize it: who it is, who it serves, what its domain model is, what conventions it adopts and — most importantly — which part of it you will build in each of the twelve modules. By the end of this lesson you will have the project skeleton created, the seed file data/events.json written, and a clear map of the destination.

1. The business context
2. The actors and what each of them needs
3. The domain model
4. The seed file data/events.json
5. The repository folder structure
6. Road map: what each module builds
7. Project conventions
8. A note on fictional data

Escena Viva is a small company that handles ticket sales for three cultural spaces in a medium-sized city:

Until now, each venue sold its own tickets: one with a spreadsheet, another over the phone, and the third with a legacy system nobody knows how to maintain. Escena Viva exists to unify all of it in a single platform.

The three events we start with — the ones you already know — are:

• Concierto de Otoño (Teatro Almendra), 2 sessions in October 2026.
• Noche de Monólogos (Sala Bóveda), 3 sessions in October 2026.
• Festival de Jazz de Primavera (Auditorio Ribera), 2 sessions in April 2027.

The requirements that drive the project's technical decisions are these:

1. Brutal, very short concurrency spikes. When a festival goes on sale, thousands of people arrive at once for ten minutes. For the rest of the month the traffic is modest.
2. Capacity cannot be oversold. That is the hard requirement: two people cannot buy the same seat.
3. Prices are real money. They tolerate no rounding errors.
4. We have to integrate with third parties: a payment gateway, an email service, and in the future a code scanner at the door.
5. The team is small. Two people develop and maintain everything, so simplicity and reusing knowledge between client and server have real value.

Points 1, 4 and 5 are exactly why, in the first lesson, we concluded that Node.js is a good fit for this business.

This separation is not decorative: it is what will justify the role-based access control in Module 8. An organizer at the Teatro Almendra must not be able to see the Sala Bóveda's revenue.

These are the system's entities. The names in the "identifier" column are the ones we will use literally in the code, in English and in plain ASCII.

And this is how they relate:

Three modeling decisions worth understanding right away:

• Capacity lives on the session, not on the event. The Teatro Almendra has 420 seats, but a particular session may only put 380 on sale if there is a press area held back. The venue supplies the maximum; the session, the reality.
• A ticket is individual and has its own code. An order of 4 tickets generates 4 ticket records, each with its own unique code, because each one is validated separately at the door.
• sold is a denormalized counter on the session. Strictly it could be worked out by counting tickets, but showing availability in the catalog has to be instantaneous. In Module 7 we will see how to keep that counter consistent using transactions.

Until Module 7, when the escena_viva database arrives, this file is the data source for the whole application. Create data/events.json with exactly this content:

JSON does not allow comments, so here they are instead:

Check that the file is valid JSON before moving on:

If the command fails with SyntaxError, there is an extra comma, an unclosed quote, or you have used single quotes. In JSON every key and every string goes in double quotes, and a trailing comma after the last element is not allowed.

We still do not know how to read this file from code with fs — that is Module 3 — but it is already in place and already the reference. From there on, src/catalog-data.js will stop carrying the data hard-coded inside it.

This is the target structure, the one the project will have at the end of the course. Do not create all of it now: it will grow with each module.

Organizing principles we will follow:

• One responsibility per folder. If you do not know where to put a file, it probably does two things.
• src/ holds only code; data/ only data; reports/ only generated results. Generated results are never version-controlled.
• File names in lower case with hyphens (catalog-data.js), never with spaces or capitals. Linux distinguishes upper from lower case even when your laptop does not, and that has broken more deployments than anyone can count.

This table is the map of the course. Keep it: every time you start a module you will know which piece of Escena Viva you are adding.

These rules apply to all the code in the course. Written down once here, we will not debate them again.

Variables, functions, classes, properties and file names are written in English, with no accents or non-ASCII characters: priceCents, availableTickets, calculateOccupancy, catalog-data.js.

The exceptions are the ones the environment imposes: language keywords (const, class, return), Node and browser APIs (readFile, createServer, map), and package names (express, mongoose).

Why no accented characters? Because an identifier such as sesión is valid JavaScript but turns into a source of bugs the moment it travels through a URL, a file name or an HTTP header. The same applies to our data: the venue and event names keep their Spanish spelling but drop the accents (Sala Boveda, Concierto de Otono).

Style: camelCase for variables and functions, PascalCase for classes, UPPERCASE_WITH_UNDERSCORES for global constants.

Every date is stored as a YYYY-MM-DDTHH:mm:ss string.

Three reasons:

1. It sorts correctly as text, with no conversion to Date.
2. It is unambiguous: 03/10/2026 is 3 October in Spain and 10 March in the United States.
3. It survives the trip through JSON. A Date object becomes text when serialized and does not come back as a Date when deserialized; if you store text already, there are no surprises.

Formatting it as 03/10/2026 20:00 is the presentation layer's job, never storage's.

Every monetary amount is stored as a whole number of cents. 2500 means 25.00 EUR.

JavaScript's number type is a double-precision float (IEEE 754) and cannot represent 0.1 exactly. With money, that error accumulates and ends up as an accounting discrepancy. Working with integers the problem disappears: you only divide by 100 at the very last moment, in order to display.

Naming convention: every monetary field carries the suffix Cents (priceCents, totalCents, discountCents). That way confusion is impossible.

Every ticket has a code in this format:

Why this format rather than a long random identifier?

• It can be read out over the phone. Someone can dictate it to customer service without mistakes.
• It is sortable and its year is visible at a glance.
• It is short enough to print under a barcode.

The trade-off is that it is predictable: if you know one code you can guess the next. That is why the code is never proof of ownership; validation at the door also checks the ticket's status in the database. It is a conscious decision, of the kind you take constantly on a real project.

All the data in this course is made up. The venues, the events, the organizers, the email addresses and the orders that will appear from Module 7 onwards correspond to no real people or companies.

This is not a formality: it is a professional practice you should carry over into your own work.

• Never use real customer data in development, in testing or in demos. Not even "just this once", not even a copy of the production database on your laptop.
• Development databases are populated with synthetic data, generated or anonymized. In Module 7 we will see how to write seeds for exactly that.
• Personal data is regulated. Names, email addresses, phone numbers and payment details carry legal obligations around processing and minimization.
• Never push secrets to the repository: payment gateway keys, database passwords or tokens. They go in environment variables (Module 11), and that is why .gitignore has included .env since the very first lesson.

When we register the user [email protected] in Module 8, notice the .test domain: it is reserved by standard for testing and will never correspond to a real mailbox.

Mistake 1: storing prices as decimals "because it is more convenient". It is, for about two weeks. Then comes the first one-cent discrepancy in a report covering 3,000 orders, and there is no way to work out where it came from.

Mistake 2: using local date formats in the data. 03/10/2026 forces you to know who wrote it in order to interpret it. ISO 8601 in storage, local format only for display.

Mistake 3: putting capacity on the event instead of on the session. It works until the first session with reduced capacity, and then you have to migrate data.

Mistake 4: leaving the JSON file as one giant line. Every change shows up in version control as "the whole line modified" and reviews become impossible. null, 2 always.

Mistake 5: mixing languages in identifiers. getEventoById, listarEvents, precioPrice. Pick one — English in this course — and be systematic.

Tip 1: go back to the road map at the start of each module. Knowing which piece you are building completely changes the way you study an API.

Tip 2: use git from day one. A git commit at the end of each lesson gives you a point of return and a history of your own learning.

Tip 3: do not run ahead. It is tempting to set up the Express server right now. Each module introduces the concepts in a deliberate order; skipping it usually ends in code that works without you understanding why.

Tip 4: when in doubt, look at the domain model. A good share of coding decisions answer themselves once you look at the entity table.

Leave the project ready for Module 2. It must satisfy:

1. The escena-viva/ folder contains src/, data/ and reports/.
2. data/events.json exists with the three events and is valid JSON.
3. reports/ is under version control even though it is empty (hint: .gitkeep).
4. .gitignore excludes node_modules/, .env, *.log and the generated contents of reports/ without excluding the folder.
5. .nvmrc contains the LTS version you installed.
6. There is a README.md with the project name, the three events and the commands to get started.
7. A first git commit with all of the above.

Write out the full sequence of commands and the contents of each file.

Add a fourth event to data/events.json with these characteristics:

• Title: Cuentos al Anochecer
• Venue: Teatro Almendra (organizer org-almendra)
• Category: family, duration 55 minutes, status published
• Three sessions on Saturdays 7, 14 and 21 November 2026 at 18:00
• Capacity 200 in each session (the Teatro Almendra holds back part of the stalls for this format)
• Tickets sold: 200, 145 and 30 respectively
• Price: 1200 cents for the first two and 900 for the third

Respect the project's id, date and price formats. Then verify with node -p commands that:

1. The file is still valid JSON and has 4 events.
2. The catalog now has 10 sessions.
3. The total capacity of the Teatro Almendra (adding up all its events) is correct.
4. There is exactly one sold-out session.

A colleague has written this snippet. Rewrite it respecting all the project conventions and explain each change.

Solution 1

.gitignore (point 4). The key is the ! exception, so the contents are ignored but the folder is kept:

README.md (point 6):

Verification and first commit (points 2 and 7):

Solution 2

The block to insert at the end of the array in data/events.json (remember the comma after the previous event's closing brace):

Verifications:

A note on point 4: ses-002-1 has 118 of 120 sold, so it is not sold out. The only sold-out one is the first session of the new event.

Solution 3

The changes applied and why:

Checking the calculation: 118 × 1800 + 45 × 1800 = 212,400 + 81,000 = 293,400 cents = 2,934.00 EUR. With decimal prices the result would have been the same in this particular case, but a price of 18.99 and a few hundred operations are enough for phantom cents to start showing up.

Escena Viva is no longer a backdrop: it is a project with a context, actors, a domain model, data and rules of its own. You have seen who uses the platform — attendee, organizer and administrator — and how that separation anticipates role-based control; you have formalized the entities event, session, ticket, order, user, organizer and venue, with their relationships and their statuses; you have written the seed file data/events.json that will be the data source until the database arrives; and you have settled the conventions that will not be debated again: identifiers in English with no accents, ISO 8601 dates, prices as whole cents, ticket codes like EV-2026-000123, JSON with null, 2 and always fictional data.

Above all, you have the road map. You know that in Module 3 the catalog will stop being hard-coded and start being read from disk, that in Module 4 it will surface over HTTP, that in Module 7 it will move into a database with transactions that make overselling impossible, and that in Module 10 you will learn to withstand the traffic spike of a festival going on sale.

That closes Module 1. You have the environment installed with an LTS version managed through .nvmrc, you know how to run and debug a script, you handle the REPL as a laboratory, you have command of the modern JavaScript we will be using, and the project is standing with its data seed in place.

What you still do not know is how Node.js works on the inside, and that is the missing piece for writing real server code. In Module 2: Core Concepts we open the box: Node's architecture, the event loop and its phases, callbacks, promises and async/await, events with EventEmitter, and the module system with require and module.exports. There, at last, the array of events hard-coded in src/catalog-data.js will become a reusable module, the Event and Session classes will be born in src/domain/, and the waiter who never waits from the first lesson will stop being an analogy and turn into the code you write.