Docs

PVC Connect Integrations service · documentation hub

Three layers, one source of truth

PVC documents every service in three layers, and each one answers a different question. All three live in the repository, change in the same pull request as the code, and are published by the service itself.

Layer 1
Storybook · "Show me the pieces of the UI."
Not applicable: backend service, no shared UI components
Layer 2
Docusaurus handbook · "Teach me about the product and the system."
56 pages · architecture, ADRs, events, data, guides →
Layer 3
OpenAPI"Tell me exactly how to call the API."37 operations ↗ XML docs + DocFX"Tell me about the .NET code."1,300+ members →
0undocumented public membersa missing XML comment fails the build
37 / 37API operations with a summarychecked by ApiDocsTests
19message pagesfield tables checked against the contracts
6architecture decisionsrecorded as ADRs

Architecture tour

One image, two roles, ports and adapters. PVC Connect calls in over REST and RabbitMQ; tax and rates come from providers behind ports.

Layers (dependencies point inwards)

  1. Api: endpoints, auth, hosting
  2. Infrastructure · Providers.AvaTax: EF Core, MassTransit, adapters
  3. Application: use cases and the ports (ITaxProvider, IExchangeRateProvider, ...)
  4. Domain: entities and rules. Contracts: DTOs and messages, shipped as a package

Architecture tests fail the build if a layer reaches the wrong way, or if the Avalara SDK escapes its adapter.

A tax document, end to end

  1. Validate, then check the scope, the entity and the feature flag
  2. Save first, using the caller's ids as the idempotency key
  3. Call AvaTax with a stable document code, so a retry adjusts the same transaction
  4. AvaTax down? Keep it PendingTax; a job finishes it later. Never guess tax.
  5. The event goes out through the outbox, only when the change commits

Read more: architecture overview · resilience · decision records · service card

Areas of the service

Each area has three doors: the handbook explains it, the API reference shows how to call it, and the .NET reference shows the code.

Tax

Estimates, AR sales tax and AP use tax, commit, credits, PendingTax, tax-code mappings, address validation.

HandbookAPI ↗Code

Exchange rates

Bank of Canada daily rates, one locked rate per pair per day, conversion with rounding only at the edges.

HandbookAPI ↗Code

Customers & certificates

Party sync behind the NDA gate, CertExpress invites, resale requests per PO, expiry watching.

HandbookAPI ↗Code

Reports & reconciliation

Sales tax by line and jurisdiction, vendor-charged tax, and the nightly comparison with AvaTax.

HandbookAPI ↗Code

Entities & rollout

Every call names an entity. Feature flags start off, so each entity can go live in stages.

HandbookAPI ↗Code

Security

JWT scopes per endpoint, per-entity access, data minimization, the demo-key guard rail.

HandbookScopesCode

Operations

Health checks, OpenTelemetry, five scheduled jobs, the runbook, Kubernetes and the free demo.

RunbookObservabilityCode

Testing

Unit, architecture, contract, integration, end-to-end, accessibility and performance, explained on its own page.

How we testHandbook

Events: one page per message

Seven messages come in from PVC Connect and twelve events go out. Each has a page: when it happens, what to do with it, routing, and a field table generated from the contract.

Consumed

Published

Topology and conventions: event catalog

Data: migrations, models and SQL comments

Migrations are the record

EF Core migrations in source control, reviewed as SQL with dotnet ef migrations script --idempotent. No .sql files kept just for documentation.

Migrations how-to →

The model, drawn

An ER diagram and a table guide in the handbook. Every property is described in the .NET reference.

Data model →

Queries say what they do

LINQ next to the code that uses it. The few raw statements carry a -- comment inside the SQL text, so it shows up in database logs too.

Query rules →

-- Scheduled-job leader election: returns false at once if another replica holds the job's lock.
-- Session-level, so it is released on unlock or when this connection drops (pod crash).
SELECT pg_try_advisory_lock(@key)

Docs as code

Documentation follows the same path as code. If it isn't in the pull request, it didn't happen.

  1. AuthorCode and docs in one branch
  2. ReviewSame pull request, same reviewer
  3. VerifyPeer review plus automated checks
  4. ReleaseThe image publishes /docs with the code

What the build checks

  • Every public type and member has an XML comment (CS1591 is an error)
  • Every API operation has a summary and a tag; every schema and property has a description
  • Every message has an event page with a field table that matches the contract
  • The handbook builds with no broken links or anchors
  • DocFX builds the .NET reference

What the reviewer checks

  • The pull request template's documentation checklist
  • Behaviour changes are reflected in the handbook
  • Big decisions have an ADR
  • A CHANGELOG.md entry under Unreleased
  • At release, the handbook is versioned with the code

Details: how we document

Quick reference: where does it go?

ToolAnswersIn this service
Storybook"Show me the pieces of the UI."Not applicable (no UI components)
Docusaurus"Teach me about the product and the system."Handbook · docs/
OpenAPI"Tell me exactly how to call the API."API reference · /openapi/v1.json
XML docs / DocFX"Tell me about the .NET code.".NET reference · IntelliSense
Git"Tell me what changed and when."Pull requests ↗ · CHANGELOG ↗
SQL comments"Tell me what this is doing to the data."Migrations · query rules

Apply it to your next microservice

Everything here is copyable. Start with the cheapest piece that enforces itself, then add the handbook.

  1. Turn on XML docs and stop suppressing CS1591. From then on the compiler keeps layer 3 honest. 
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  2. Serve OpenAPI and a reference at /docs/api, give every route .WithSummary, and copy ApiDocsTests.
  3. Copy build/docfx for the .NET reference at /docs/code/.
  4. Copy website/ and start docs/ from the templates: intro, product, architecture overview, service card, ADRs, events, database, developer guide.
  5. Generate event tables from the contracts (event-pages.py plus EventDocsTests), and write the prose by hand.
  6. Add the PR template, a CHANGELOG, and a CI docs job, and build the docs into the image.

The playbook · checklist · templates (service card, event page, ADR, XML docs)