Skip to content

Getting Started

Welcome! This guide helps you get oriented before diving into the full documentation.

What is PQ?

PQ is a cloud-native physical access control platform. It manages doors, readers, inputs, outputs, and other security hardware through a unified event-driven architecture.

Your job as an adapter developer is to bridge your device to PQ: translate device events into PQ domain events, and route PQ commands back to the device.

What You Build vs. What the Framework Provides

You provide Framework provides
Vendor SDK / protocol knowledge NATS message bus integration
Device communication logic Event routing to server
Event translation Command dispatch and routing
Command execution on device Access sync engine (diff, ordering, hashing)
Thing configuration in YAML Persistence (LiteDB)
Connection retry and lifecycle management
UI and ABAC engine integration

The framework generates a significant portion of the boilerplate from your YAML configuration — Thing classes, function state machines, typed command and event classes.

How an Adapter Fits In

PQ Server (API, UI, ABAC)
        │
        │  NATS (events, commands, status)
        │
  Adapter Process
        │  ├─ Your protocol/SDK code
        │  └─ Generated framework scaffolding
        │
  Physical Device(s)

Where to Start

Step 1 — Understand the architecture (15 min) Read 00-overview.md. Pay attention to the Thing hierarchy, Functions, and the YAML-to-code generation workflow.

Step 2 — Pick your adapter family (10 min) Browse archetypes/ and find the shape closest to your device's protocol (TCP, HTTP streaming, gRPC, native SDK, CCTV).

Step 3 — Build the minimal adapter (10 min) Follow tutorials/00-hello-world.md. You will have a compiling, running adapter skeleton before reading anything else.

What a Finished Adapter Looks Like

Pq.Adapter.Vendor.Product/
├─ adapter-registration.yaml     # Device types, functions, commands — you write this
├─ access-model.yaml             # Credential sync entities (optional)
├─ Communication/
│   ├─ Protocol.cs               # Device communication — always required
│   └─ Transport.cs              # Custom transport — only for gRPC/serial/SDK processes
├─ Devices/
│   ├─ ControllerDevice.cs       # Extend generated Thing classes
│   └─ DoorDevice.cs
└─ Commands/
    └─ DoorCommands.cs           # Command handler methods

Typical adapter: 8–15 files, most of the complexity in Protocol.cs and event translation logic. Generated code handles the rest.

Key Reference Documents

Keep these open while implementing:

When You Get Stuck

  1. Check 03-troubleshooting.md — covers the most common build, connection, and event issues
  2. Search the concepts/ directory for the specific area (commands, events, address resolution, …)
  3. Check patterns/ for the nearest matching implementation pattern