Architecture 101: Frameworks, Monorepos and How Modern Apps Fit Together

Summary

You finished Course 1 by shipping a real site, and Course 2 by turning your agent into a power tool. Now you graduate from a single static site to a real application with users, data and payments. Before any of that, you need the map. This lesson is that map: what a framework actually does for you, the three layers every app is built from, why serious teams split a fast marketing site from the heavier app, and when a monorepo is a gift versus a tax. Get this clear and every later decision in this course stops feeling arbitrary.

What you will learn

You will learn the difference between frontend, backend and database in plain language, how the main 2026 frameworks compare and when each fits, why companies like Clerk and Convex run a separate marketing site from their app, and the honest rule for when a monorepo pays for itself. By the end you can sketch the architecture of any SaaS on a napkin and explain why it is shaped that way.

Prerequisites

Course 1, especially the project setup and deploy lessons, since architecture decisions build on a working build-and-ship loop. You should be comfortable running terminal commands and have deployed at least one site. If the words "framework" or "TypeScript" are still fuzzy, skim the Fundamentals pages on what a framework is and what TypeScript is first, then come back.

The problem

Most beginners glue an app together by copying whatever a tutorial did, with no model of how the pieces relate. Then they hit a wall: the marketing page is slow because it is bundled with the whole app, auth and data are tangled into the UI, and nobody can say where a given responsibility lives. The result is an app that is hard to change and impossible to reason about. None of that is a coding skill problem. It is a missing mental model. This lesson installs the model so your agent builds on solid ground instead of a pile of copied snippets.

The three layers: frontend, backend, database

Every web app, no matter how fancy, is three layers handing work to each other. The frontend is what runs in the browser: the HTML, CSS and JavaScript that draw the screen and react to clicks. The backend is the code that runs on a server, away from the user, where you put logic and secrets you do not want the browser to see. The database is where data lives permanently so it survives a page refresh and is shared between users. A request flows one way and back: the browser asks the backend for something, the backend reads or writes the database, and sends an answer the browser renders. Most confusion about "where does this code go" dissolves the moment you can name which of these three layers a piece of work belongs to.

• Frontend: runs in the browser, draws the UI, never holds secrets, anyone can read it.
• Backend: runs on a server, holds business logic and API keys, talks to the database.
• Database: stores data permanently and shares it across users and sessions.
• Golden rule: a secret (API key, password) belongs in the backend, never in frontend code, because the browser ships its code to every visitor.

What a framework gives you

A framework gives you structure, routing and conventions so you are not assembling an app from raw files. It decides how URLs map to pages, how pages fetch data, how the app is bundled and served, and a hundred small things you would otherwise reinvent. The 2026 options each lean a different way, and the right pick depends on how much of your product is content versus app.

• Astro: built for fast, content-heavy sites - blogs, docs, marketing pages. Ships almost no JavaScript by default, so pages load fast and rank well. Reach for it when most of your product is content.
• Next.js: the heavyweight React framework for rich, interactive apps. Huge ecosystem, server rendering, and the default many teams choose for a full product app.
• TanStack Start: a newer full-stack React framework built on TanStack Router, with excellent type safety and a lighter, more transparent feel. This very platform runs on TanStack Start.
• Vue (with Nuxt): the main alternative to React. Same job, different syntax and philosophy. Pick it if you or your team already think in Vue.

You do not need to master all four. Pick one app framework and one content framework and stick with them. A common, sane combination is Astro for the marketing site and a React framework (Next.js or TanStack Start) for the app. The exact names matter less than understanding the axis: content-fast versus app-rich.

The marketing-site versus app split

Here is the pattern that confuses beginners until someone points it out: serious products run their public marketing site and their logged-in app as two separate things, often on two subdomains. Look at Clerk and Convex themselves - the homepage at the bare domain is a fast marketing site, and the dashboard lives at a separate address. They are not the same codebase serving both. The reason is that the two surfaces have opposite needs. Public marketing pages must be lightning fast and fully indexable by Google and AI crawlers, because that is how you get found. The logged-in app can be heavier and richly interactive, because by then the user has already arrived and signed in, and SEO no longer matters. Bundling them together forces a bad compromise: either your marketing pages drag in the whole app and load slowly, or your app is hamstrung by marketing-page constraints. Splitting them lets each be optimised for its real job.

• Marketing site: bare domain (yoursite.com), fast, SEO and GEO optimised, often Astro. Its job is to get found and convert visitors.
• App: a subdomain (app.yoursite.com), heavier, interactive, behind auth. Its job is to deliver the product. SEO does not matter here.
• Auth and dashboards (Clerk) and your database (Convex) live on the app side, never bundled into the marketing pages.
• This split is why your homepage can score 100 on Lighthouse while your app is a rich, stateful React experience.

What a monorepo is, and when it helps

A monorepo is a single Git repository that holds several related projects - say your marketing site, your app and a shared package of components - instead of one repo per project. The appeal is real: you share code (types, UI components, utilities) across surfaces without publishing packages, and one pull request can change everything that needs to change together. The cost is real too: monorepos add tooling overhead (workspace managers, more complex builds, slower CI if you are careless) that a solo beginner does not need on day one. The honest rule: reach for a monorepo when you genuinely share meaningful code across two or more surfaces and the duplication is hurting you. Until then, separate repos are simpler and perfectly fine. Do not adopt a monorepo because a big company does - they have hundreds of engineers and you have an agent and a laptop.

• Monorepo: one repo, many projects, shared code, coordinated changes.
• Worth it when: marketing site and app share types or components, and you change them together often.
• Skip it when: you have a single app, or two surfaces that barely share code. The overhead is not free.
• You can always start with separate repos and merge into a monorepo later when the pain is real.

Typical mistakes

The recurring errors at this stage: bundling the marketing site and app into one project, then wondering why the homepage is slow and SEO suffers; putting a secret API key in frontend code where every visitor can read it; adopting a monorepo on day one because it looks professional, and drowning in build configuration; and choosing a framework by hype rather than by whether your product is content-heavy or app-heavy. Every one of these comes from skipping the mental model. Name the layer, name the surface, and the right structure follows.

Business ROI

Architecture decided well at the start is nearly free; decided badly, it taxes every future change. A clean marketing-versus-app split means your homepage stays fast and gets found, which is the top of your entire funnel - slow marketing pages quietly cost you customers and search ranking forever. Knowing which layer owns which responsibility means you (and your agent) ship features without creating tangles that later need expensive rewrites. The founders who move fastest are not the ones who picked the trendiest framework; they are the ones whose architecture lets them change one thing without breaking three others.

Checklist

Before you move on, make sure you can answer these without looking back. This map sits under every other lesson in the course.

• Can you explain frontend, backend and database, and which one holds secrets?
• Can you say when you would pick Astro versus Next.js or TanStack Start?
• Can you explain why teams split the marketing site from the app?
• Can you state the honest rule for when a monorepo is worth it?

Resources

Keep the official docs for your chosen frameworks bookmarked - Astro, Next.js, TanStack Start and Nuxt all have excellent getting-started guides. The Fundamentals pages on what a framework is and what TypeScript is back up this lesson if a concept stayed fuzzy. The next three lessons fill in the three layers one by one: auth, then data, then the secrets that connect them.

Your task

Sketch your own product (or a product you admire) as a diagram with three boxes - frontend, backend, database - and an arrow showing a request flowing through them. Then mark which parts are the marketing site and which are the app. Five minutes with a pen makes the rest of this course concrete, because you now have a real shape to attach each new piece to.

Next lesson

With the architecture clear, the next lesson adds the first real building block: authentication with Clerk, including what OAuth actually is, why you must never build auth yourself, and a full Google OAuth walkthrough from a development instance to production.