For six modules, Escena Viva has lived off a single file: data/events.json. It served us well. It taught us fs.promises, it let us build a rich domain with Event and Session, and it fed both the node:http server of Module 4 and the Express API of Module 6. But when we closed that module we left a promise unkept: the capacity and overselling problem was not going to be solved with validation or with well-typed errors, because it is not a problem of shape or of state — it is a problem of concurrency and persistence. That problem is the doorway into this module.

We are not going to write a Mongoose schema or a CREATE TABLE statement just yet. We are going to do something more important: understand what we are missing, what a database management system gives us and at what price, how to choose between the relational and the document worlds without joining a tribe, and how to design Escena Viva's data model. By the end you will have the complete blueprint of what we will build across the next five lessons.

1. Why a JSON file stops being enough
2. What a DBMS actually gives you
3. Relational versus document
4. ACID, BASE and the CAP theorem applied to capacity
5. The database landscape for Node.js
6. Native driver versus ORM/ODM
7. Designing Escena Viva's data model
8. The final model in a diagram
9. Isolating persistence: the repository pattern
10. Installing MongoDB and checking the connection

Let's be honest and concrete. src/catalog-data.js is not a bad module: it reads data/events.json with fs.promises, memoizes the result and exposes getCatalog() and getEventById(). The problem is not its code, it is its storage model. These are the real — not theoretical — failures Escena Viva already has today:

• Concurrent writes that overwrite each other. If two requests sell tickets at the same time, both read the file, both modify their in-memory copy and both rewrite it whole. The last write wins and the first sale disappears. There is no lock, no arbitration, nobody deciding the order. It is exactly the overselling scenario.
• Non-atomic writes. A writeFile of the entire catalog can be interrupted (disk failure, SIGKILL, container restart) leaving a truncated JSON file. A truncated JSON file is not a catalog with one event missing: it is a file that no longer parses, and the application will not start.
• The whole catalog in memory. With 3 events and 7 sessions it is free. With 40,000 historical events, every Node process loads megabytes it never queries. Process memory is an expensive resource, shared with the event loop.
• No efficient queries. "Give me the sessions at Teatro Almendra between March 1st and 15th that still have tickets available" is solved today by walking the entire array in JavaScript. That is O(n) over the whole data set, on the main thread, with no way to improve it unless you write an index yourself.
• No integrity. Nothing stops an order from pointing at ses-999-9, a session that does not exist. Nothing stops sold from exceeding capacity. The invariants live only in the domain classes, and if somebody edits the JSON by hand or a script bypasses the domain, the data is corrupt forever.
• No history. The file only holds the current state. How many tickets were sold last Tuesday? Who cancelled the order? There is no answer: the previous state was overwritten.
• No access from multiple processes. This is the one that hurts most looking ahead. In Module 10 we will meet cluster and start several Node processes to use every core on the machine. With a JSON file, each process would have its own in-memory cache and its own idea of capacity; they would not even find out about each other's sales. File persistence makes scaling impossible. And in Module 11, deploying with PM2 or with several container replicas, the problem is multiplied by the number of instances.

The conclusion is not that files are bad. A JSON file is perfect for configuration, for seed data, for exporting a report. It is bad as a store of shared, mutable, concurrent state. And that is precisely what a session's capacity is.

A database management system (DBMS) is a specialized process, usually on another machine or in another container, whose only job is to look after data. In exchange for learning it and operating it, it gives you six things you are not going to reimplement well:

Look at the last row. It is the one that solves the problem we have been dragging along, and we will devote half of lesson 07-06 to it.

There are two big families a Node developer runs into every day. Neither is "modern" and the other "old"; neither is "serious" and the other "a toy". They are models with different trade-offs.

The healthy way to read this table: pick the model that looks like your access pattern. If your application almost always reads "one event with all its sessions", the document model gives you that in a single disk read. If your application almost always joins five entities to produce a report, the relational model gives you that in a single optimized query.

Escena Viva, curiously, has both faces: the catalog is document-shaped by nature (an event contains its sessions) and selling is relational by nature (orders, tickets, users and money). That is why this module does both: MongoDB will be the official persistence layer in lessons 2 to 4, and in lessons 5 and 6 we will model the same thing in PostgreSQL to see what changes — and discover that overselling is solved there in a particularly elegant way.

ACID describes the guarantees of a transaction. Atomicity: the transaction happens whole or it does not happen. Consistency: when it finishes, every schema rule still holds. Isolation: two simultaneous transactions never see each other half-done, and the result is as if they had run in some order. Durability: once committed, it survives a server failure. Relational systems were born with ACID and document systems have been adopting it. BASE is the opposite trade-off, typical of massively distributed systems: Basically Available (it always answers), Soft state (state may be in transit), Eventually consistent (if you stop writing, at some point every replica will agree). BASE trades immediate correctness for availability and scale.

The CAP theorem explains why that trade exists. In a distributed system where the network can partition (and it always can), you cannot keep strong consistency (C) and total availability (A) at the same time: when two nodes stop seeing each other, either you reject writes so as not to diverge, or you accept them and you will diverge. Since partition tolerance (P) is not optional on a real network, the practical decision is between CP (I reject doubtful writes and stay correct) and AP (I accept everything and reconcile later).

Applied to Escena Viva: capacity demands strong guarantees. Selling one ticket too many is not a cosmetic detail that gets fixed "eventually"; it is a person holding code EV-2026-000431 standing at the door of Teatro Almendra with no seat, plus a refund, plus a complaint. The sold counter is the textbook example of data that needs immediate consistency: we would rather reject a doubtful purchase (CP) than accept it and discover afterwards that there was no room. Other data on the very same platform, by contrast, tolerates eventual consistency perfectly well: the view count on an event page, the recommendations, or the catalog cache we will build with Redis in Module 10. The guarantee is chosen per piece of data, not per application.

Redis deserves a clarification because it is widely misread: it is not "a faster database", it is an in-memory database with a different durability model. You put it in front of the primary database, not in its place. In Module 10 we will use it to cache the catalog and to queue confirmation emails.

Between your code and the engine there is always a driver: it speaks the database's binary protocol and exposes a low-level API. On top of it there may be an ORM (Object-Relational Mapper, the SQL world) or an ODM (Object-Document Mapper, the document world), which translates between rows or documents and JavaScript objects.

What an ORM/ODM gives you: less repetitive code, declarative validation, coherent types, hooks, migrations and one shared mental model for the whole team. What it takes away: transparency. One innocent line can generate 200 queries (the N+1 problem we will see in lesson 07-04). The professional rule is: use the ORM for 95% of the code and do not be afraid to drop down to raw queries for the 5% that matters, measuring before you decide. In this module we will use Mongoose (ODM) and Sequelize (ORM), and in both cases we will see how to escape to the raw query.

Before writing a schema you have to decide what counts as an entity. An entity is something with its own identity and its own life cycle: it exists before and after the operation that created it, and it makes sense to look it up on its own. An event is an entity. An order is an entity. The venue's name, by contrast, is an attribute.

The second decision is what gets grouped together and what gets kept apart. In the document world this is called embedding versus referencing and we will study it thoroughly in lesson 07-04, but we can already apply the criterion with two questions:

1. Are they always read together? If you never ask for a session without its event, group them.
2. Does it grow without bound? If the child collection grows indefinitely, keep it apart.

Let's apply that to our entities:

• Event with its sessions embedded. An event has between 1 and 7 sessions in our catalog; a play in a long run might have 60. That is a bounded number, known in advance. On top of that, the event detail screen and the API itself (GET /events/:id) always ask for them together: even today the listEventSessions controller starts from a loaded Event. And their size is tiny. They are embedded.
• Order as a separate collection. Orders grow without a ceiling: a popular event can accumulate tens of thousands. They have their own life cycle (pending → paid → issued | cancelled) and are queried on their own ("my orders"). Putting them inside the event would grow the document until it burst the size limit, and would force rewriting it whole on every purchase. They are kept apart.
• Ticket as a separate collection. Every ticket has its unique code EV-2026-000431, its status (valid → used | cancelled) and is validated individually at the door, by scanning. It is the smallest unit of access in the system and the one with the highest volume. It is kept apart, with references to the order and to the session.
• User as a separate collection, with its role (attendee, organizer, administrator). In this module we create it with no passwords and no authentication: that is entirely Module 8. Here we only leave the slot ready.

And a third decision, deliberately uncomfortable: the sold counter lives inside the session, even though it could be computed by counting valid tickets. It is denormalization on purpose, so that checking capacity is a single field read instead of an aggregation. The price is keeping the counter coherent with the real tickets; we pay that price with the techniques of lesson 07-06.

Read it like this: SESSION appears as an entity in the diagram because conceptually it is one, but physically it lives inside the EVENT document as a subdocument. ORDER and TICKET are independent collections related by reference. This is the blueprint we will implement in lesson 07-02 with Mongoose and translate into tables in 07-05 with Sequelize — where SESSION will be a table of its own, and we will see why.

Here comes the most important architectural warning of the module. If controllers call Event.find(...) directly, your application is married to MongoDB forever. Changing engines, or testing with fake data, or querying two different sources, would mean rewriting every controller.

The solution is a thin layer: src/repositories/. A repository exposes operations in the language of the business (getCatalog, getEventById, reserveCapacity, createOrder) and hides completely how they are fulfilled. Above it, controllers and domain do not know whether Mongo, Postgres or an array sits underneath.

Notice the decisive detail: it is exactly the public signature of src/catalog-data.js. That is why we will be able to swap the whole module out without touching src/controllers/events.js. And that is why, in lesson 07-05, we will write a second implementation on top of Sequelize without changing a single line of the application. The repository returns domain objects (Event, Session), not Mongoose documents: that way the domain keeps its getters (occupancy, soldOut) and its invariants, exactly as we left them in Module 2.

Three routes, all valid. Pick one.

Option A: local service. Install MongoDB Community Server from the official site and run it as a system service:

Option B: Docker. The cleanest one, because it does not dirty your machine and it is removed with a single command. In Module 11 we will formalize this with docker compose:

Option C: MongoDB Atlas. The managed service in the cloud. Its free tier is enough for this course; it will give you a URL like mongodb+srv://user:[email protected]/escena_viva. This is what you will use in production if you would rather not operate the engine yourself.

Whichever option you choose, check the connection with the official mongosh client:

And inside the shell:

One quirk that surprises people: MongoDB does not create the database or the collection until the first document. If show dbs does not list escena_viva right after you connect, that is not an error.

The connection URL will never be written by hand in the code. It goes in .env and is read from src/config/index.js, already the only point in the application that touches process.env:

And with the connection verified, it pays to settle in advance what questions the application will ask, because a data model is designed backwards from the queries. These are Escena Viva's five most frequent queries, and they are the ones that will govern the indexes in lesson 07-02:

• Choosing the engine because it is fashionable. "We use Mongo because it's JavaScript" is not a criterion. The criteria are the access pattern, the guarantees you need and what your team knows how to operate.
• Believing that "schemaless" means "no design". MongoDB does not force you to declare a shape, but your data has one anyway. If you do not decide it, every insert you write will decide it for you, and you will end up with seven variants of the same document.
• Putting the connection URL in the code. With credentials inside it, pushed to git. It goes in the configuration, always. You already have the place: src/config/index.js.
• Leaving the database with no authentication "because it's development". A MongoDB exposed on 27017 with no user is one of the favorite targets of automated scanners. Locally, at the very least do not publish the port outside localhost.
• Tip: before modeling, write down the five queries your application will run most often. A data model is designed backwards from the queries, not forwards from the entities.
• Tip: keep data/events.json. We will not delete it: in lesson 07-06 it becomes the seed that loads the database. It retires as a store, not as a source.

Open src/catalog-data.js and src/controllers/orders.js and find, without running anything, the exact points where two simultaneous requests can corrupt the state. For each one, write down: which line reads, which line writes, and what happens if another request sneaks in between them.

Escena Viva wants to add two things: (a) the reviews attendees leave about an event, and (b) the seating plan of each venue. For each one, decide whether it is embedded or kept apart and justify the decision with this lesson's two criteria (read together and growth).

Classify these four pieces of data according to whether they need strong or eventual consistency, and justify it: (1) a session's sold, (2) the view counter on an event page, (3) the status of an order, (4) the list of "events recommended for you".

Exercise 1. The dangerous pattern is always read-modify-write without mutual exclusion. In the purchase flow: the memoized catalog is read, session.available >= quantity is checked, session.sell() is called and the result is persisted. If two requests run the check before either of them writes, both pass it even when only one ticket is left. Memoization makes things worse: the in-memory copy can be minutes out of date with respect to the file. And because Node is single-threaded, the gap opens exactly at every await — the event loop from Module 2 yields its turn right there.

Exercise 2. (a) Reviews are kept apart: they grow without bound (a festival can accumulate thousands), they are not needed to render the catalog, they are paginated and sorted by date, and they are moderated with a life cycle of their own. (b) The seating plan is embedded in the venue (or referenced as a separate catalog if several venues share a template), because it is bounded in size, it changes almost never and it is always read together with the venue. Careful, though: the occupancy of each seat in a specific session is volatile and write-heavy, so that state must not live in the static plan.

Exercise 3. (1) sold: strong, it is the very definition of the overselling problem. (3) Order status: strong, it decides whether money is charged and whether tickets are issued; a stale read can double a charge. (2) Views: eventual, a 2% error for a few seconds harms nobody and in exchange lets you count in memory and flush in batches. (4) Recommendations: eventual, they are computed offline and nobody notices they are an hour behind.

We have closed the file chapter. You now know, with concrete names, what data/events.json lacks: atomicity, concurrency, queries, indexes, integrity, history and multi-process access. You know what a DBMS gives you in exchange, what separates the relational model from the document model without needing to take sides, and why capacity belongs to the territory of strong guarantees under ACID and CAP. You have seen the real landscape of engines for Node and the trade-off between dropping down to the native driver and leaning on an ORM/ODM. And, above all, you have Escena Viva's data model decided and reasoned out: Event with its sessions embedded, Order, Ticket and User as separate collections, with the sold counter denormalized on purpose.

You also have the architectural piece that holds up the whole module: src/repositories/, the boundary that will stop the database engine from leaking into the controllers and the domain.

In the next lesson we go down into the code. We will connect to MongoDB from src/config/index.js, write src/db/connection.js with its opening at startup and its closing in the graceful shutdown that already exists in src/server.js, and translate this diagram into Mongoose schemas and models in src/models/: types, validators, virtuals, schema middleware and indexes. The blueprint becomes structure.