A Family Investment Dashboard — In Your Browser

Portfolio 60 is a web application that tracks investments for a UK family. It shows how much each person's Trading, ISA, and SIPP accounts are worth — all converted to British pounds.

What Happens When You Open the App?

Imagine you type the address into your browser and hit Enter. Here's the journey your request takes — from your browser all the way to the database and back.

The Server's Front Door

This is the actual code that starts the server and handles every single request. It's the first thing that runs.

const server = Bun.serve({
  port: port,
  hostname: hostname,
  idleTimeout: 0,

  async fetch(request) {
    const url = new URL(request.url);
    const path = url.pathname;

    const authResponse = checkAuth(path);
    if (authResponse) return authResponse;
  }
});

The Full Request Journey

Here's the complete path every request takes, from your browser to the database and back.

Check Your Understanding

A Post Office With Specialist Departments

Think of Portfolio 60 like a post office. Mail arrives at the front desk (the server entry point), gets sorted to the right department, and each department has specialists who know exactly how to handle their type of mail.

The codebase is organised into clear layers. Each layer has one job and talks only to its neighbours.

Where Everything Lives

Here's the project's folder structure. Each folder maps to one of the actors above.

The Switchboard Operator — The Custom Router

Portfolio 60 doesn't use a framework for routing. It has a tiny, hand-built router — just 116 lines of code — that matches incoming URLs to the right handler.

add(method, path, handler) {
  const paramNames = [];
  const patternString = path.replace(
    /:([a-zA-Z_]+)/g,
    function(match, paramName) {
      paramNames.push(paramName);
      return "([^/]+)";
    }
  );
  const pattern = new RegExp("^" + patternString + "$");
  this.routes.push({ method, pattern, paramNames, handler });
}

How the Layers Talk to Each Other

Watch how a real request flows through the system. When you ask for your portfolio summary, here's the conversation between the components.

Check Your Understanding

A Library With a Single Librarian

Most web apps use big database servers like PostgreSQL or MySQL. Portfolio 60 uses SQLite — a database that's just a single file on your hard drive.

Think of it like a private library with one librarian. There's no network, no queue, no separate building. The librarian sits right inside the app and answers queries instantly.

Opening the Database — Once and Only Once

The singleton pattern ensures the database is opened once and shared everywhere.

let db = null;

export function getDatabase() {
  if (db) {
    return db;
  }

  db = new Database(dbPath);
  db.exec("PRAGMA journal_mode = WAL");
  db.exec("PRAGMA foreign_keys = ON");
  db.exec("PRAGMA busy_timeout = 5000");

  return db;
}

The Money Trick — Why Everything Is Multiplied by 10,000

Computers are bad at decimal maths. Try 0.1 + 0.2 in JavaScript and you get 0.30000000000000004. That's a disaster when tracking real money.

Portfolio 60's solution: never store decimals. Instead, multiply every number by 10,000 and store it as a whole number. When it's time to display, divide by 10,000.

export const CURRENCY_SCALE_FACTOR = 10000;

// Storing a price:
const scaledPrice = Math.round(
  priceMinorUnit * CURRENCY_SCALE_FACTOR
);

// Reading a price:
price: row.price / CURRENCY_SCALE_FACTOR

Time Travel — How Holdings Remember Their History

When you sell half your shares, the app doesn't just overwrite the old number. It closes the old record with an end date and opens a new one. This means you can ask "what did my portfolio look like last March?" and get the exact answer.

This technique has a name: SCD2 — Slowly Changing Dimension Type 2. It's the same technique used in data warehouses at large companies.

Check Your Understanding

Three News Wires, One Newsroom

Portfolio 60 gets its data from three external APIs — like a newsroom that subscribes to three different news wires, each specialising in a different type of information.

Order Matters — Rates First, Then Prices

When the app fetches new data, it always gets currency rates before investment prices. Why? Because a US share price in dollars is meaningless until you know today's USD-to-GBP rate. The rates and prices need to be from the same moment in time.

How Currency Rates Are Fetched

This is the actual code that calls the European Central Bank's API to get today's exchange rates.

const FRANKFURTER_API_URL =
  "https://api.frankfurter.dev/v1/latest";

const symbols = nonGbpCurrencies
  .map(function(c) { return c.code; })
  .join(",");

const url = FRANKFURTER_API_URL
  + "?base=GBP&symbols=" + symbols;

Watch a Price Fetch in Action

Click through each step to see how the scheduled fetcher collects and stores data.

It Happens Automatically — Scheduled Fetching

You don't have to click "fetch" every day. A cron job inside the app triggers a full price update on a schedule. If it fails, it retries automatically.

Check Your Understanding

The Recipe — How Raw Numbers Become Your Portfolio Value

Imagine a currency exchange desk at an airport. You hand over your foreign currency, they check today's rate, multiply, and give you pounds. Portfolio 60 does this at scale — for every holding, in every account, for every person.

The valuation recipe has three ingredients:

The Maths — One Line Per Holding

For each holding, the calculation is simple. For a GBP investment, it's just price times quantity. For foreign currency, there's one extra step — divide by the exchange rate.

const valueLocal = price * holding.quantity;

const valueGBP =
  holding.currency_code === "GBP"
    ? valueLocal
    : valueLocal / ratesMap[holding.currency_code];

Rolling It Up — From Holdings to the Household Total

The service builds a hierarchy: holdings roll up into accounts, accounts into users, users into the household total. Think of it like a spreadsheet with subtotals.

Time Travel Valuations

Remember SCD2 from Module 3? This is where it pays off. You can ask "what was my portfolio worth on 15 June 2024?" and the service will:

Check Your Understanding

No Framework — And That's the Point

Most modern web apps use a frontend framework like React or Vue. Portfolio 60 deliberately doesn't. It uses plain HTML served from the server, with vanilla JavaScript adding interactivity.

Think of it like building furniture from solid wood instead of buying flat-pack. It takes a bit more initial effort, but there are no mysterious framework bugs, no build pipeline to debug, and the code is readable by anyone who knows basic JavaScript.

How a Page Loads Data

Each page follows the same pattern: the HTML loads, then JavaScript calls the API to fetch data, then renders it into the page.

Custom Building Blocks — Web Components

The navbar and footer appear on every page. Instead of copying HTML, they're built as web components — custom HTML tags like <app-navbar> that the browser knows how to render.

class AppNavbar extends LitElement {
  createRenderRoot() {
    return this;
  }
  render() {
    return html`
      <nav class="bg-brand-800 text-white">
        <h1>Portfolio 60</h1>
        <ul>...menu items...</ul>
      </nav>
    `;
  }
}

Check Your Understanding

Debugging Is Detective Work

When something goes wrong, the key skill isn't knowing the answer — it's knowing where to look. Think of it like a detective following a trail of evidence. Each layer of the app gives you clues, and the error message is the first clue.

Portfolio 60's layered architecture makes this easier. If the symptom is "wrong number on screen," you can trace backwards through the layers to find where the data went wrong.

Security — The Bouncer's Playbook

Portfolio 60 protects financial data with a passphrase system. But security isn't just about having a password — it's about thinking about all the ways someone could get in without one.

Testing — The Safety Net

Tests are like a checklist a pilot runs before every flight. They catch problems before they reach users. Portfolio 60 has two types.

// Each test file gets its own database
process.env.DB_PATH =
  "data/portfolio_60_test/test.db";

// Each test file gets its own port
process.env.PORT = "1441";

describe("Holdings DB", () => {
  test("creates a holding", () => {
    const h = createHolding({...});
    expect(h.id).toBeDefined();
  });
});

The Full Picture — Everything Connected

Now you've seen every piece. Here's how it all fits together — from the browser at the top to the external APIs at the bottom.

Debugging in Action

A user reports: "My portfolio total looks way too high." Watch how you'd trace through the layers to find the bug.

Final Check

You've Seen Behind the Curtain

You now know how a real web application works — from the browser to the database and back. Every concept here applies to thousands of other apps. Use this knowledge to steer AI tools better, debug smarter, and build with confidence.