> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nearnode.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How NearNode bridges physical triggers to digital actions at the edge.

## The Core Principle

The hardware is **static** (read-only NFC chips, printed QR codes). The logic is **liquid** (managed in the database). This decoupling is NearNode's core architectural advantage.

```
Physical Trigger          Edge Network           Your Logic
┌──────────┐         ┌─────────────────┐     ┌──────────────┐
│ NFC Tag  │──scan──▶│ /v/:slug        │────▶│ Redirect URL │
│ QR Code  │         │ Resolve + Route │     │ vCard        │
│ Sticker  │         │ Log Analytics   │     │ WiFi Config  │
└──────────┘         └─────────────────┘     │ Microsite    │
                                              │ Action       │
                                              └──────────────┘
```

## Capability Layers

NearNode is built in six layers, each adding capability on top of the shared edge infrastructure:

| Layer | Name                | Purpose                                            |
| ----- | ------------------- | -------------------------------------------------- |
| 0     | **Edge Middleware** | `/v/:slug` — resolve slug, execute function        |
| 1     | **Orchestration**   | Routing rules: A/B splits, time-based, geo, device |
| 2     | **Fleet**           | Batch operations, serial IDs, hardware lifecycle   |
| 3     | **Payloads**        | vCard, Microsite, WiFi, Action types               |
| 4     | **Intelligence**    | Analytics, TTR, alerts, conversion tracking        |
| 5     | **Enterprise**      | Multi-tenancy, RBAC, custom domains                |

## The Edge Request Flow

When a user scans a QR code or taps an NFC tag, here's exactly what happens:

<Steps>
  <Step title="DNS Resolution">
    The scan hits `nearnode.io/v/:slug`. DNS resolves to Vercel's global edge network.
  </Step>

  <Step title="Slug Lookup">
    Edge middleware queries the `nodes` table by slug. Target: **sub-200ms** globally.
  </Step>

  <Step title="Kill Switch Check">
    If the node is deactivated, lost, or retired → the user sees a block page. No redirect fires.
  </Step>

  <Step title="Rule Evaluation">
    Routing rules are evaluated **top-to-bottom by priority**. First match wins. If no rules match, the node's base payload is used as fallback.
  </Step>

  <Step title="Analytics Logging">
    A scan event is logged asynchronously with device type, country, city, and a session ID for conversion tracking. **Non-blocking** — doesn't add latency.
  </Step>

  <Step title="Execution">
    Based on the resolved function type:

    * **Redirect** → 307 to destination URL
    * **vCard** → Serve `.vcf` download
    * **WiFi** → Render one-tap connect page
    * **Action** → Direct to WhatsApp, Calendly, email, etc.
  </Step>
</Steps>

## Infrastructure Stack

<CardGroup cols={2}>
  <Card title="Supabase (PostgreSQL)" icon="database">
    Database, auth, and Row Level Security. Hosted in **Frankfurt, Germany** (AWS eu-central-1).
  </Card>

  <Card title="Vercel Edge Network" icon="globe">
    Application hosting and edge functions. Global CDN with **EU priority routing**.
  </Card>
</CardGroup>

## Performance Targets

| Metric                               | Target       |
| ------------------------------------ | ------------ |
| `/v/:slug` TTFB (no routing rules)   | **\< 200ms** |
| `/v/:slug` TTFB (with routing rules) | **\< 350ms** |
| Dashboard LCP                        | **\< 1.5s**  |
| Batch generation (100 nodes)         | **\< 5s**    |
| Bundle size (first load)             | **\< 120KB** |

## Security Model

<AccordionGroup>
  <Accordion title="Row Level Security (RLS)" icon="lock">
    Every table in the database has RLS policies that scope queries to the user's organization. Even if a query is malformed, PostgreSQL enforces data isolation at the database level.
  </Accordion>

  <Accordion title="API Key Scoping" icon="key">
    API keys are bound to an organization. They cannot access data from other orgs. Keys can be rotated and revoked instantly from the dashboard.
  </Accordion>

  <Accordion title="RBAC Roles" icon="users">
    Four roles — **Owner**, **Admin**, **Editor**, **Viewer** — control who can create, modify, and delete resources. Enforced on both the UI and API layers.
  </Accordion>

  <Accordion title="Kill Switch" icon="power-off">
    Any node can be instantly deactivated. The kill switch takes effect immediately — no cache delay. Scans to killed nodes are logged as `kill_switch_blocked` events.
  </Accordion>
</AccordionGroup>