# thiagond-code/codelab architecture

> Architecture diagram of the GitHub repository thiagond-code/codelab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiagond-code/codelab
- Repository: https://github.com/thiagond-code/codelab

## Overview

This repository is a small Node.js backend lab with multiple parallel implementations of the same basic backend stack. The code is organized to compare a plain Node server, a routed Node server, and an Express-based server, each paired with either SQLite or Supabase data access.

1. **Top-level intent**
   - `README.md` is minimal, so the architecture is inferred from the folder layout.
   - The repo is structured as a set of backend experiments rather than a single monolithic application.
   - The repeated `mvp`, `routes`, `db`, `sqlite`, and `supabase` folders suggest a teaching/codelab style where the same backend is built in different layers.

2. **Main backend area**
   - All meaningful code lives under `backend/node`.
   - This subtree contains two major concerns:
     - HTTP/server runtime examples.
     - Database access examples.
   - Each subproject has its own `package.json`, so these are independently runnable packages rather than one shared build.

3. **Plain Node server path**
   - `backend/node/server` is the framework-free server variant.
   - It is split into:
     - `mvp/` for the minimal server entry point.
     - `routes/` for a slightly more structured server with routing.
   - This implies a progression from a bare server to a layered HTTP API.

4. **Server layering**
   - The `server/mvp/index.ts` files are likely the simplest HTTP bootstrap: start the server and handle requests directly.
   - The `server/routes/index.ts` files likely introduce route dispatching and separation between request handling and business logic.
   - The presence of these two variants indicates the server boundary is a core architectural theme.

5. **Database layer**
   - `backend/node/db` is the data-access side of the repo.
   - It contains two storage adapters:
     - `sqlite/`
     - `supabase/`
   - Both adapters have their own entry points and `package.json`, so they are implemented as standalone data-access modules.

6. **SQLite adapter**
   - `db/sqlite/userQueries.ts` is the clearest sign that the data layer is query-oriented and focused on a `user` domain model.
   - `db/sqlite/index.ts` is the module entry point for SQLite-backed operations.
   - The presence of `api.rest` suggests the folder may also include sample REST requests for exercising that backend.

7. **Supabase adapter**
   - `db/supabase/dbconfig.ts` indicates external service configuration lives separately from the rest of the code.
   - `db/supabase/index.ts` is the execution entry point for the Supabase-backed data layer.
   - This is the cloud/external-database boundary of the repo, distinct from the local SQLite path.

8. **Express framework variant**
   - `backend/node/frameworks/express` mirrors the plain Node layout but swaps in Express as the HTTP framework.
   - It contains both:
     - `server/mvp/` and `server/routes/`
     - `db/sqlite/` and `db/supabase/`
   - This shows the repo is comparing the same app architecture across runtime/framework choices.

9. **Architecture boundary pattern**
   - The repeated structure suggests a clean separation into:
     - HTTP layer: server startup and routing.
     - Data layer: database queries and backend service adapters.
     - Infrastructure choice: SQLite vs Supabase.
     - Framework choice: raw Node vs Express.
   - The code likely keeps the domain logic thin, with most variation happening at the edge layers.

10. **Data flow**
   - Typical flow is likely: request enters server → route or handler resolves action → database module runs query/operation → response returned.
   - In the SQLite path, the data flow stays local and embedded.
   - In the Supabase path, the flow crosses an external API/service boundary.

11. **Tooling and packaging**
   - Multiple `package.json` files imply each example is self-contained and can be run or installed independently.
   - `package-lock.json` files indicate npm is the package manager.
   - TypeScript is used throughout (`.ts` files), so the repo is compiled/transpiled rather than pure runtime JavaScript.

12. **Supporting files**
   - `api.rest` files appear alongside the database implementations, likely to document or test endpoints manually.
   - `.gitignore` files exist in several subprojects, reinforcing that each folder is treated like a standalone mini-app.

If you are drawing an architecture diagram, the clearest representation is a set of parallel stacks:
- Plain Node server stack
- Express server stack
- SQLite-backed data stack
- Supabase-backed data stack

Each stack shares the same conceptual layers, but swaps the HTTP framework and/or persistence adapter at the boundaries.

Main entry points: [`backend/node/server/package.json`](https://github.com/thiagond-code/codelab/blob/master/backend/node/server/package.json) (Node server), [`backend/node/frameworks/express/server/mvp/index.ts`](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/mvp/index.ts) (Express server), [`backend/node/db/package.json`](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/package.json) (DB layer), [`backend/node/frameworks/express/db/sqlite/index.ts`](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/index.ts) (Express DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_root["Node lab"]
  node_n_root["Backend lab<br/>repo root"]
end

subgraph group_g_server["Plain Node"]
  node_n_plain_server["Node server<br/>runtime variant<br/>[package.json]"]
  node_n_plain_mvp["MVP server<br/>bootstrap<br/>[index.ts]"]
  node_n_plain_routes["Route server<br/>router layer<br/>[index.ts]"]
end

subgraph group_g_db["Data access"]
  node_n_db_layer["DB layer<br/>data stack<br/>[package.json]"]
  node_n_sqlite[("SQLite<br/>local adapter<br/>[index.ts]")]
  node_n_sqlite_queries["User queries<br/>query module<br/>[userQueries.ts]"]
  node_n_supabase[("Supabase<br/>remote adapter<br/>[index.ts]")]
  node_n_supabase_config["DB config<br/>service config<br/>[dbconfig.ts]"]
end

subgraph group_g_express["Express stack"]
  node_n_express["Express stack<br/>framework variant<br/>[package.json]"]
  node_n_express_server["Express server<br/>http layer<br/>[index.ts]"]
  node_n_express_mvp["MVP server<br/>bootstrap<br/>[index.ts]"]
  node_n_express_routes["Route server<br/>router layer<br/>[index.ts]"]
  node_n_express_db["Express DB<br/>data stack<br/>[index.ts]"]
  node_n_express_sqlite[("SQLite<br/>local adapter<br/>[index.ts]")]
  node_n_express_sqlite_queries["User queries<br/>query module<br/>[userQueries.ts]"]
  node_n_express_supabase[("Supabase<br/>remote adapter<br/>[index.ts]")]
  node_n_express_supabase_config["DB config<br/>service config<br/>[dbconfig.ts]"]
end

node_n_root -->|"contains"| node_n_plain_server
node_n_root -->|"contains"| node_n_db_layer
node_n_root -->|"contains"| node_n_express
node_n_plain_server -->|"variant"| node_n_plain_mvp
node_n_plain_server -->|"variant"| node_n_plain_routes
node_n_db_layer -->|"adapter"| node_n_sqlite
node_n_db_layer -->|"adapter"| node_n_supabase
node_n_sqlite -->|"uses"| node_n_sqlite_queries
node_n_supabase -->|"uses"| node_n_supabase_config
node_n_express -->|"contains"| node_n_express_server
node_n_express -->|"contains"| node_n_express_db
node_n_express_server -->|"variant"| node_n_express_mvp
node_n_express_server -->|"variant"| node_n_express_routes
node_n_express_db -->|"adapter"| node_n_express_sqlite
node_n_express_db -->|"adapter"| node_n_express_supabase
node_n_express_sqlite -->|"uses"| node_n_express_sqlite_queries
node_n_express_supabase -->|"uses"| node_n_express_supabase_config
node_n_plain_mvp -.->|"progression"| node_n_plain_routes
node_n_plain_server -.->|"pairs with"| node_n_db_layer
node_n_express_server -.->|"pairs with"| node_n_express_db

click node_n_plain_server "https://github.com/thiagond-code/codelab/blob/master/backend/node/server/package.json"
click node_n_plain_mvp "https://github.com/thiagond-code/codelab/blob/master/backend/node/server/mvp/index.ts"
click node_n_plain_routes "https://github.com/thiagond-code/codelab/blob/master/backend/node/server/routes/index.ts"
click node_n_db_layer "https://github.com/thiagond-code/codelab/blob/master/backend/node/db/package.json"
click node_n_sqlite "https://github.com/thiagond-code/codelab/blob/master/backend/node/db/sqlite/index.ts"
click node_n_sqlite_queries "https://github.com/thiagond-code/codelab/blob/master/backend/node/db/sqlite/userQueries.ts"
click node_n_supabase "https://github.com/thiagond-code/codelab/blob/master/backend/node/db/supabase/index.ts"
click node_n_supabase_config "https://github.com/thiagond-code/codelab/blob/master/backend/node/db/supabase/dbconfig.ts"
click node_n_express "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/package.json"
click node_n_express_server "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/mvp/index.ts"
click node_n_express_mvp "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/mvp/index.ts"
click node_n_express_routes "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/routes/index.ts"
click node_n_express_db "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/index.ts"
click node_n_express_sqlite "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/index.ts"
click node_n_express_sqlite_queries "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/userQueries.ts"
click node_n_express_supabase "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/supabase/index.ts"
click node_n_express_supabase_config "https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/supabase/dbconfig.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_root toneBlue
class node_n_plain_server,node_n_plain_mvp,node_n_plain_routes toneAmber
class node_n_db_layer,node_n_sqlite,node_n_sqlite_queries,node_n_supabase,node_n_supabase_config toneMint
class node_n_express,node_n_express_server,node_n_express_mvp,node_n_express_routes,node_n_express_db,node_n_express_sqlite,node_n_express_sqlite_queries,node_n_express_supabase,node_n_express_supabase_config toneRose
```

## Components

### Node lab

Core backend experiments under backend/node

- **Backend lab**: repo root · Parallel Node.js backend implementations

### Plain Node

Framework-free server variants

- [Node server](https://github.com/thiagond-code/codelab/blob/master/backend/node/server/package.json): runtime variant · Framework-free HTTP server stack · `backend/node/server/package.json`
- [MVP server](https://github.com/thiagond-code/codelab/blob/master/backend/node/server/mvp/index.ts): bootstrap · Minimal server entry point · `backend/node/server/mvp/index.ts`
- [Route server](https://github.com/thiagond-code/codelab/blob/master/backend/node/server/routes/index.ts): router layer · Server variant with route dispatching · `backend/node/server/routes/index.ts`

### Data access

SQLite and Supabase adapters

- [DB layer](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/package.json): data stack · Standalone database access examples · `backend/node/db/package.json`
- [SQLite](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/sqlite/index.ts): local adapter · SQLite-backed data access · `backend/node/db/sqlite/index.ts`
- [User queries](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/sqlite/userQueries.ts): query module · SQLite query definitions for the user domain · `backend/node/db/sqlite/userQueries.ts`
- [Supabase](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/supabase/index.ts): remote adapter · Supabase-backed data access · `backend/node/db/supabase/index.ts`
- [DB config](https://github.com/thiagond-code/codelab/blob/master/backend/node/db/supabase/dbconfig.ts): service config · Supabase connection/configuration boundary · `backend/node/db/supabase/dbconfig.ts`

### Express stack

Express-based mirror of the same backend layers

- [Express stack](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/package.json): framework variant · Express-based mirror of the backend stack · `backend/node/frameworks/express/package.json`
- [Express server](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/mvp/index.ts): http layer · Express HTTP server variants · `backend/node/frameworks/express/server/mvp/index.ts`
- [MVP server](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/mvp/index.ts): bootstrap · Minimal Express server entry point · `backend/node/frameworks/express/server/mvp/index.ts`
- [Route server](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/server/routes/index.ts): router layer · Express server with routing · `backend/node/frameworks/express/server/routes/index.ts`
- [Express DB](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/index.ts): data stack · Express-scoped database examples · `backend/node/frameworks/express/db/sqlite/index.ts`
- [SQLite](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/index.ts): local adapter · Express + SQLite data access · `backend/node/frameworks/express/db/sqlite/index.ts`
- [User queries](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/sqlite/userQueries.ts): query module · Express SQLite query definitions · `backend/node/frameworks/express/db/sqlite/userQueries.ts`
- [Supabase](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/supabase/index.ts): remote adapter · Express + Supabase data access · `backend/node/frameworks/express/db/supabase/index.ts`
- [DB config](https://github.com/thiagond-code/codelab/blob/master/backend/node/frameworks/express/db/supabase/dbconfig.ts): service config · Express Supabase configuration boundary · `backend/node/frameworks/express/db/supabase/dbconfig.ts`

## Connections

- Backend lab → Node server: contains · Plain Node server experiments
- Backend lab → DB layer: contains · Standalone database access experiments
- Backend lab → Express stack: contains · Express-based mirror stack
- Node server → MVP server: variant · Minimal entry point
- Node server → Route server: variant · Routed entry point
- DB layer → SQLite: adapter · Local SQLite implementation
- DB layer → Supabase: adapter · Remote Supabase implementation
- SQLite → User queries: uses · Query definitions for user data
- Supabase → DB config: uses · External service configuration
- Express stack → Express server: contains · Express HTTP variants
- Express stack → Express DB: contains · Express-scoped data access variants
- Express server → MVP server: variant · Minimal Express bootstrap
- Express server → Route server: variant · Express routing layer
- Express DB → SQLite: adapter · Express + SQLite implementation
- Express DB → Supabase: adapter · Express + Supabase implementation
- SQLite → User queries: uses · Query definitions for the Express SQLite path
- Supabase → DB config: uses · Configuration for Supabase access
- MVP server → Route server: progression · From direct handling to routed dispatch
- Node server → DB layer: pairs with · Same backend ideas with separate data stack
- Express server → Express DB: pairs with · Express runtime paired with database access