# larbish/nuxt3-supabase-example architecture

> Architecture diagram of the GitHub repository larbish/nuxt3-supabase-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/larbish/nuxt3-supabase-example
- Repository: https://github.com/larbish/nuxt3-supabase-example

## Overview

1. This repository is a small Nuxt 3 application that acts as a frontend for a Supabase-backed todo list. There is no custom server API or application backend in the repo; the app talks directly from the browser to Supabase.

2. The main architectural split is:
   - Nuxt/Vue UI layer in `app.vue` and `pages/`
   - Authentication/session handling via Supabase and route middleware
   - Data persistence in Supabase Postgres through the Supabase client

3. `pages/index.vue` is the public entry route, while `pages/todo.vue` is the authenticated application screen where todo data is shown and manipulated. In Nuxt terms, the `pages/` directory defines the route map.

4. `middleware/auth.ts` is the route guard boundary. It protects the todo area by checking authentication state before allowing access, and likely redirects unauthenticated users away from the private page.

5. `auth.ts` at the repository root is a shared auth-related module. In a project like this, that file typically centralizes login/logout/session logic or Supabase auth helpers used by the pages and middleware.

6. The Supabase integration is the backend boundary. Per the README, the app uses:
   - Supabase Auth for user management
   - Supabase’s Postgres-backed REST/data API for todo records
   This means persistence and identity are delegated to a managed external service.

7. `types/tasks.d.ts` defines the task data contract used by the UI and data access code. That type boundary helps keep the frontend aligned with the expected Supabase `tasks` table shape.

8. `app.vue` is the Nuxt application shell. It provides the top-level layout/root outlet that all routed pages render into, so it sits above the page-specific todo/auth flows.

9. The runtime stack is Nuxt 3 + Vue 3, styled with Tailwind, and configured through `nuxt.config.ts`. The repo is TypeScript-first (`tsconfig.json`), so the architecture is strongly typed at the UI/data boundary.

10. End-to-end data flow is straightforward:
   - User opens the site
   - Nuxt renders the public page
   - User authenticates through Supabase
   - Middleware allows access to `/todo`
   - The todo page reads/writes task rows through Supabase
   - Supabase persists the data in hosted Postgres and returns results to the client

11. Operationally, the only required external configuration is the Supabase project URL and key in environment variables. The app is therefore designed for deployment as a static/SSR frontend with managed auth and database services behind it.

Main entry points: [`pages/todo.vue`](https://github.com/larbish/nuxt3-supabase-example/blob/main/pages/todo.vue) (Todo page), [`nuxt.config.ts`](https://github.com/larbish/nuxt3-supabase-example/blob/main/nuxt.config.ts) (Nuxt config), [`auth.ts`](https://github.com/larbish/nuxt3-supabase-example/blob/main/auth.ts) (Auth helpers), [`app.vue`](https://github.com/larbish/nuxt3-supabase-example/blob/main/app.vue) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI layer"]
  node_app_shell["App shell<br/>Nuxt root<br/>[app.vue]"]
  node_public_page["Home page<br/>Route view<br/>[index.vue]"]
  node_todo_page["Todo page<br/>Private view<br/>[todo.vue]"]
end

subgraph group_auth["Auth boundary"]
  node_route_guard{{"Auth guard<br/>Route middleware<br/>[auth.ts]"}}
  node_auth_module["Auth helpers<br/>Shared auth<br/>[auth.ts]"]
end

subgraph group_data["Data boundary"]
  node_task_types["Task types<br/>Type contract<br/>[tasks.d.ts]"]
  node_supabase_auth[("Supabase auth<br/>Managed auth")]
  node_supabase_api["Data API<br/>Supabase client"]
  node_postgres[("Postgres<br/>Hosted DB")]
end

subgraph group_config["Project setup"]
  node_nuxt_config["Nuxt config<br/>Framework config<br/>[nuxt.config.ts]"]
  node_package_manifest["Package manifest<br/>Deps & scripts<br/>[package.json]"]
end

node_app_shell -->|"renders"| node_public_page
node_app_shell -->|"renders"| node_todo_page
node_public_page -->|"login flow"| node_auth_module
node_todo_page -->|"protected by"| node_route_guard
node_route_guard -->|"checks session"| node_auth_module
node_auth_module -->|"delegates"| node_supabase_auth
node_todo_page -->|"reads/writes"| node_supabase_api
node_supabase_api -->|"persists"| node_postgres
node_todo_page -->|"uses"| node_task_types
node_auth_module -.->|"shares shapes"| node_task_types
node_nuxt_config -->|"configures"| node_app_shell
node_nuxt_config -->|"routes"| node_public_page
node_nuxt_config -->|"routes"| node_todo_page
node_package_manifest -.->|"depends on"| node_nuxt_config
node_supabase_auth -.->|"authorizes"| node_supabase_api

click node_app_shell "https://github.com/larbish/nuxt3-supabase-example/blob/main/app.vue"
click node_public_page "https://github.com/larbish/nuxt3-supabase-example/blob/main/pages/index.vue"
click node_todo_page "https://github.com/larbish/nuxt3-supabase-example/blob/main/pages/todo.vue"
click node_route_guard "https://github.com/larbish/nuxt3-supabase-example/blob/main/middleware/auth.ts"
click node_auth_module "https://github.com/larbish/nuxt3-supabase-example/blob/main/auth.ts"
click node_task_types "https://github.com/larbish/nuxt3-supabase-example/blob/main/types/tasks.d.ts"
click node_nuxt_config "https://github.com/larbish/nuxt3-supabase-example/blob/main/nuxt.config.ts"
click node_package_manifest "https://github.com/larbish/nuxt3-supabase-example/blob/main/package.json"

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_app_shell,node_public_page,node_todo_page toneBlue
class node_route_guard,node_auth_module toneAmber
class node_task_types,node_supabase_auth,node_supabase_api,node_postgres toneMint
class node_nuxt_config,node_package_manifest toneRose
```

## Components

### UI layer

Nuxt app shell and routed screens

- [App shell](https://github.com/larbish/nuxt3-supabase-example/blob/main/app.vue): Nuxt root · Top-level Nuxt container that renders routed pages · `app.vue`
- [Home page](https://github.com/larbish/nuxt3-supabase-example/blob/main/pages/index.vue): Route view · Public entry screen for the app · `pages/index.vue`
- [Todo page](https://github.com/larbish/nuxt3-supabase-example/blob/main/pages/todo.vue): Private view · Authenticated screen for reading and updating todos · `pages/todo.vue`

### Auth boundary

Session checks and access control

- [Auth guard](https://github.com/larbish/nuxt3-supabase-example/blob/main/middleware/auth.ts): Route middleware · Protects private routes by checking user session state · `middleware/auth.ts`
- [Auth helpers](https://github.com/larbish/nuxt3-supabase-example/blob/main/auth.ts): Shared auth · Centralized login, logout, and session utilities · `auth.ts`

### Data boundary

Task data contracts and Supabase persistence

- [Task types](https://github.com/larbish/nuxt3-supabase-example/blob/main/types/tasks.d.ts): Type contract · Shared task shape used by UI and data access code · `types/tasks.d.ts`
- **Supabase auth**: Managed auth · External user and session management service
- **Data API**: Supabase client · Browser-side access to todo records via Supabase
- **Postgres**: Hosted DB · Persistent store for todo rows behind Supabase

### Project setup

Framework and build configuration

- [Nuxt config](https://github.com/larbish/nuxt3-supabase-example/blob/main/nuxt.config.ts): Framework config · Project configuration for Nuxt and runtime behavior · `nuxt.config.ts`
- [Package manifest](https://github.com/larbish/nuxt3-supabase-example/blob/main/package.json): Deps & scripts · Dependency and script definition for the app · `package.json`

## Connections

- App shell → Home page: renders · Root shell mounts the public route
- App shell → Todo page: renders · Root shell mounts the authenticated route
- Home page → Auth helpers: login flow · Public screen uses shared auth actions
- Todo page → Auth guard: protected by · Private page is gated by route middleware
- Auth guard → Auth helpers: checks session · Middleware relies on shared auth/session logic
- Auth helpers → Supabase auth: delegates · Login and session state are handled by Supabase Auth
- Todo page → Data API: reads/writes · Todo screen talks directly to Supabase from the browser
- Data API → Postgres: persists · Todo records are stored in hosted Postgres
- Todo page → Task types: uses · Todo UI is typed by the shared task contract
- Auth helpers → Task types: shares shapes · Auth-related code can reference task/user-related types
- Nuxt config → App shell: configures · Framework setup drives the Nuxt app shell
- Nuxt config → Home page: routes · Nuxt page routing is defined by the pages directory
- Nuxt config → Todo page: routes · Nuxt page routing is defined by the pages directory
- Package manifest → Nuxt config: depends on · Project dependencies and scripts support the Nuxt setup
- Supabase auth → Data API: authorizes · Authenticated client state gates data access
