Admin (Internal)

Internal operational docs and runbooks live here.

Build organization pedigree templates

Open Pedigree editor from the parent organization workspace. Choose an existing template and its front or back page, or create a new template by copying a known starting point. Legacy HTML templates remain unchanged until an administrator explicitly selects Start visual editing.

The visual editor is the normal design surface. Add text, dynamic dog and organization fields, ancestry cards, images, organization/FCI logos, shapes, and lines from the element library. Drag or resize each item on the A4 canvas; use the grid, alignment, layer, lock, duplicate, undo, and redo controls for precise placement. An ancestry card can show or hide its relationship label, registration number, chip, date of birth, color, HD, ED, DNA, and titles. The front-page starter includes parents through four generations.

The canvas uses the same typed renderer as pedigree preview and issuance, so its geometry and styles are the printed output. Use Page settings for orientation and background artwork. Use Advanced HTML only for legacy maintenance or export; generated visual HTML is read-only until an administrator explicitly detaches it, which permanently returns that page to legacy HTML editing. Save creates the normal organization revision and Restore or Revision history remains available for rollback.

Uploaded assets stay organization-scoped. Only supported fields and valid ancestry relationships are accepted; unknown element types, invalid colors, oversized geometry, and invalid file identifiers fail closed.

For a bilingual dynamic field arranged in one row, the labels use only their natural width and the value receives the remaining space. Choose Keep on one line to prevent a second row and safely truncate content that cannot fit, or choose Allow wrapping when preserving the complete value is more important. Widen the element or reduce its font size when a long value must remain fully visible on one line.

Manage pedigree-book prefixes

Parent kennel organizations configure prefix meaning and mating outcomes under Organization settings → Prefix Management. The visible prefix codes stay under Basic → Pedigree book prefixes; Prefix Management declares which codes count as recognized ancestry evidence and which locally issued prefix a completed mating may produce. The UI follows FCI terminology: Main Studbook and Appendix (Supplementary/Initial/B-Register). Existing internal external metadata keys remain compatibility identifiers only.

The litter Pedigree Builder reads organization-scoped prefixes for both parents and the configured ancestor depth. Missing or ambiguous evidence fails closed and identifies the exact dog that the office must resolve. Select Resolve prefix, choose a configured prefix, enter the required audit reason, and explicitly choose whether the existing guarded allocator should also create a registration number. The evaluator then reloads the pedigree and recalculates its suggested outcome.

Pedigree issuance uses the same evaluator. It blocks incomplete evidence or a prefix that conflicts with the evaluated outcome and stores a policy/evidence snapshot with the issued file so later rule edits cannot rewrite the historical decision. No prefix or number is inferred or written in bulk.

Rules may apply to Local birth, Imported dog, or Any registration. The litter Puppies and Issue tabs evaluate every puppy from its confirmed sire and dam, then offer the one configured prefix outcome as an explicit recommendation. Two-sire litters therefore may produce different recommendations per puppy. The office cannot save a conflicting prefix, and a puppy without a confirmed sire remains unresolved.

Imported-dog pedigree review uses the same organization policy against the locked, canonical pedigree saved for the request. Each known ancestor is classified from its configured pedigree-book prefix; the office does not manually label nodes as FCI or non-FCI. Approval and registration-number issuance are blocked when ancestry is missing or ambiguous, no policy rule matches, or the selected prefix differs from the calculated outcome. Parent administrators reviewing a child-organization request still allocate the number and record to the child organization that owns the request.

Review a litter and issue pedigrees

The litter office drawer gives authorized organization staff one place to decide whether a litter is ready for the pedigree book. Start with Overview for the current stage and next unresolved action, then review Breeding compliance, Health & DNA, Puppies, Viewer, Pedigree, and Issue in order. Payment, office status, kennel, and contact context remain visible in the drawer header while the review tabs stay available during scrolling.

In Puppies → Identity, the breed starts with the breed submitted for the litter. Change it only when a puppy's recognized outcome is different after birth, such as a smooth/rough or short/long-haired breed distinction. Select the puppy's coat type separately. The saved puppy breed—not the litter default— is used when Dogg creates or updates the dog record and renders the pedigree. Both fields are part of the readiness check.

In Health & DNA, review the sire before the dam. Dogg shows each current DNA, hip, and elbow result that is public, was issued by this organization, or was explicitly shared with this organization. A private result is identified without exposing its value. Use Ask owner to share results to send the current owner an in-app notification and email with a direct approval action. The owner is warned that withholding evidence may delay registration and that organization custody cannot later be revoked. Results issued by another kennel organization remain private until separately shared with the reviewing organization.

The mating-outcome table distinguishes not added yet from private — sharing required. A puppy outcome is calculated only when the reviewing organization can access both parent results. This prevents a private genotype from being inferred through the outcome. Organization staff should never ask an owner to send health evidence through an unapproved external channel.

Run the authoritative checks in Breeding compliance before relying on the readiness result. A deterministic failed breeding-rule check blocks issuance unless an authorized reviewer requests an exception and a different authorized person approves it with a decision reason. The approval is bound to the exact evidence checked; changed evidence requires a new evaluation and decision. Pending or unknown evidence cannot be excluded, and an exception never bypasses payment, owner confirmation, puppy identity, registration-number, template, prefix, or parentage requirements.

For a two-sire litter, enable More than one sire on Overview and select the second candidate. Review parentage as two separate pairs: Sire A x Dam and Sire B x Dam. Every active puppy must have a verified match and a confirmed sire before pedigree issuance. In Issue, select each puppy's pedigree type, organization template, pedigree-book prefix, optional print note, and confirmed sire. Save the configuration before issuing.

Readiness runs, exception requests and decisions, parentage evidence references, pedigree configurations, and issuance events remain in audit history. Revisions and Audit log are the final drawer tabs so operational review stays separate from historical evidence.

View the site as a user

Platform administrators can open Admin → Users and choose Log in as user for an eligible ordinary account. The user view opens in a separate tab, while the original admin tab remains signed in as the administrator.

The user-view tab is intentionally read-only. Its amber Viewing as user banner identifies both the target user and the administrator, and Return to admin ends that bounded support session. Attempts to save, delete, submit, or otherwise change data are blocked. This read-only boundary allows support staff to inspect onboarding for organization owners and managers without granting a write-capable session. Platform administrators, the current administrator's own account, disabled accounts, and pending imported accounts cannot be impersonated.

The first page and every later link must keep the amber banner visible. If a saved administrator organization points at a parent organization that the target user does not manage, Dogg automatically opens the same tool in the target user's active direct organization. A support tab must never silently return to administrator access; use Return to admin to end it explicitly.

A copied incognito link remains single-use and must be opened within 15 minutes. After it is redeemed, the active read-only support session renews while that browser session remains open and in use. It ends when Return to admin or Sign out is selected, when an administrator revokes it, or when the administrator or target account is no longer eligible. An abandoned session expires after 30 days without a successful heartbeat.

End a support preview before signing in

A support preview is read-only and stays separate from your own account. If the sign-in page says that a support preview is active, select End support preview and sign in. Wait for the ordinary sign-in form to appear before entering your account details.

An old preview that has already ended or expired is removed automatically. If the preview cannot be ended, the sign-in form stays unavailable and your current account is not changed; select End support preview and sign in to try again.

The users list can be sorted by selecting a column heading such as Role or Last login. Select the same heading again to reverse direction. On a phone, use the sort controls above the user cards. Missing dates always remain at the end of a sorted list.

Manage a user's organization access

From Admin → Users, choose Manage organization access for the relevant account. The drawer shows every active and inactive organization membership, the compatibility membership role, and the effective access roles used by the organization permission system.

Enter an audit reason before making a change. You can add an organization, change its membership and access roles, reactivate preserved access, or deactivate access without deleting membership history. The selected membership role's required base access cannot be removed. Parent organizations and child clubs use separate allowlisted role catalogs; arbitrary permission JSON is not accepted.

The last active organization owner cannot be demoted or deactivated. Assign or promote another owner first. If the membership changed in another admin window, reload it instead of overwriting the newer state. Every successful change saves the administrator, target user, organization, reason, previous state, new state, and time in the organization audit history.

Club Management for child dog clubs

The Club Management workspace is a breed-scoped directory for a child dog club. It is not a kennel-management profile for the organization itself.

The parent kennel club controls the scope in Organization settings → Child Clubs. Open the child club, assign every breed it manages, and save. The child club then sees only registered kennels connected to those breeds, including reviewed imported registry relationships. Opening a kennel keeps its dogs, litters, titles, and health summaries inside the same breed scope.

If no breeds are assigned, the directory intentionally stays empty and explains where the parent organization must complete the setup. Never work around this state by granting the child club access to every parent-club kennel.

Dog Titles Management

The organization dog drawer separates title work into Show Awards, Champion Titles, Show History, and Champion Certificates.

• Show Awards contains only show-level awards and exposes country, source, event type, verification, and any confirmed title that used the award.
• Champion Titles distinguishes calculated eligibility, applications, confirmed/custom titles, and missing requirements. Eligibility never confirms a title automatically.
• Show History contains every known participation/result, including results with no award.
• Champion Certificates are versioned records tied to a confirmed title and active organization template.

Office safety rules:

• Never guess an unresolved CAC/CACIB event type.
• Never count unverified, revoked, duplicate, or wrong-country evidence.
• A manual override requires authorization and an explicit reason.
• International titles may omit country only when configured as global.
• Dates display as DD/MM/YYYY.

Country champion title rules

Admins manage country championship programs at /[locale]/admin/titles/rule-sets. The sidebar entry is Admin → Title rules. Open a country program to review its readiness, titles, award types, and advanced identifiers.

Use the Titles tab for normal changes. Select a title, edit its requirements, review the plain-language summary and diagnostics, then save. The editor preserves advanced requirements even when they are not changed in the simple form. Unsaved changes are protected when switching titles, creating another title, or leaving the editor.

Before relying on a program for eligibility:

• resolve every missing award token or show-tag diagnostic
• keep national award tokens scoped to the program country
• use the international title level only for rules intended to count awards across countries
• verify age gates, distinct judges/shows, time spans, prerequisite titles, and CACIB-tagged requirements
• use Advanced to export the complete JSON definition for review or support

Award and show-tag edits are explicit saves. Deletes and organization-link changes require confirmation. Missing dog dates of birth and malformed or unknown rule nodes fail closed rather than granting eligibility.

Pedigree Book default ordering

The Pedigree Book opens with the newest dog identities first. For identities such as 11111/22 or 11111/2022, the final two or four digits are treated as the registration year; dogs are ordered by year first and then by the numeric identity within that year. Organizations that use plain identity numbers are ordered from the highest number to the lowest. Records without a usable identity remain after numbered records.

Historical IKC service payments

Link puppy-registration pricing to a pedigree template

Organization finance managers can connect each service priced under Puppy Registration to a template maintained in Pedigree Editor. In Payments Management, choose Puppy Registration under Revenue source, choose the required Template in the same service row, and select Save changes.

The list uses the current organization's templates. If a selected template is later removed, choose an available replacement before saving. Changing the revenue source away from Puppy Registration removes that service's template link. Template design content and revision history are not shown on the payments page, and only users with finance-management permission can save this setting.

Authorized organization finance and registry-office users can review imported IKC form payments in two places:

• Pedigree Book → dog details → Admin → Payment history shows historical service orders linked to the selected dog’s registration number. A champion-certificate payment includes the exact certificate type when the legacy record provides it.
• Finance Management → Transactions defaults to New system payments and offers separate Imported Old IKC records and All sources views. Search, status, source, totals, pagination, and CSV export follow the selected source; every row keeps a visible source label.

The historical ledger remains separate from native Dogg carts so the same transaction is not silently counted twice. Owner totals use a uniquely matched user, normalized email, or normalized phone; ambiguous identities remain separate. Missing dog or owner matches do not block the import and are retained for later review.

New-system payment statuses

• Paid — funds were confirmed.
• Pending payment — payment is still required or awaiting confirmation.
• Canceled — the request ended without payment or service authorization.
• Fee waived — an authorized employee granted the service without collecting its configured fee.

A fee waiver is not recorded as paid revenue. The finance record retains the expected fee, records zero collected and the waived amount, and identifies the reason, employee, service, related record, and time. The transaction summary and CSV report expose waived-service count and total fees waived so the treasurer can review them quickly.

For office ownership changes, selecting Fee waived requires a category and explanatory reason. Only an Office Manager, Office Staff member, or platform administrator may use this option. In the verified ownership-transfer modal, choose Office waives fee; the current owner still receives and enters the verification code, but checkout is skipped. The employee, time, standard fee, dog, category, and reason are recorded in Finance for treasurer review. The waiver and transfer request are stored in the same database transaction.

The ownership-transfer screen guides users through three choices: dog, new owner, and payment. A known new owner receives an in-site notification that opens the request. Payment or a fee waiver never changes ownership automatically: after current-owner verification and payment resolution, the new owner must review and explicitly accept the transfer. Outgoing transfers appear as single-row history entries whose drawer contains the full status and a link to payment and invoices.

Source documents are inventoried separately. A document count does not mean the file has already been copied into Dogg storage.

Connect dog owners, accounts, and kennel names

Office managers and office staff can correct identity connections from:

• Memberships → Dog Owners Management
• Kennel Management → Users
• Kennel Management → a kennel → Owners

To connect or replace a Dogg account, open the owner drawer, find Account connection, search by verified name or email, select the account, enter the office reason, and confirm the change. A matching name, shared email, or phone number is evidence for review; it is never enough by itself to connect people.

To remove an account connection, enter the reason and choose Remove connection. This preserves the imported person, dogs, kennel records, and the previous connection history. It does not delete either account.

Dog Owners Management also includes Kennel name connection. Search for the registered kennel, select it, and enter a reason before connecting or removing it. The same owner/account connection can be reviewed from the registered kennel's Owners tab.

Every manual change records the office employee, reason, prior connection, new connection, and time. A linked historical IKC identity remains a separate, auditable source record, including its imported historical dog count.

When several imported or operational records are explicitly connected to the same Dogg account, Dog Owners Management shows one canonical person row. Searching by any connected email, phone format, name, or old drawer link opens that same row. The drawer's Connected records section lists the preserved membership, pedigree-owner, kennel-owner, IKC-import, and app-account sources. Office staff can manage or remove an individual connection there without deleting its dogs, memberships, kennel history, or audit trail. Phone numbers are displayed in the organization-friendly national format while retaining the normalized international number for matching.

Import safety

• The scraper is read-only against IKC and resumable by page and record.
• Private source payloads are restricted to organization-scoped server paths and are never returned by the UI APIs.
• The importer is dry-run by default and requires an exact pedigree_staging confirmation before applying.
• Import reruns upsert only the same organization/source record ID; they do not delete existing payments, dogs, owners, or files.

Connect NordVPN for Pedigree Spider

Pedigree Spider uses a separate VPN network so approved source requests do not leave through the Dogg.dog host's public address. Connecting a VPN does not enable crawling or pedigree changes.

Create manual setup service credentials in Nord Account under NordVPN's manual setup area. Do not use your normal Nord Account email and password.

In Admin → Pedigree Spider → Safety & policy, choose Set up NordVPN:

1. read the security summary;
2. choose the VPN country;
3. enter the manual service username and password once;
4. connect, then verify protected egress.

The credentials are not stored in the Dogg.dog database or browser storage. The page never displays or stores the raw public IP. If the page says the host operator is not activated, nothing was saved; ask the infrastructure operator to complete the separately approved activation runbook.

The main page and VPN setup do not wait for the large historical reconciliation count. Open Sources to calculate those counts separately. If that calculation is temporarily unavailable, the page remains usable and offers Try again; this does not affect VPN setup or start a crawl.

If saving service credentials fails, follow the specific message shown in the drawer. Use the manual service username and password (each at least eight characters), wait one minute after too many attempts, and reload only when the secure-session message asks you to. A failed attempt never enables crawling. Do not repeatedly press Save while an attempt is still in progress.

After verification, source approval, zero-write adapter testing, and canonical promotion remain separate mandatory gates.

Organization finance management

Organization Finance is scoped to the active organization. A kennel-club administrator may see child data only when the hierarchy permission permits it; a club administrator manages only that club's records.

Authorized finance administrators configure tax in Finance → Settings. Child organizations may inherit the parent policy or explicitly override it. A root organization uses its own policy. Tax can be disabled or enabled with a 0–100% rate, display label, and inclusive or exclusive pricing. Changes affect new finalized transactions only; historical transactions keep the tax policy and amounts captured at finalization. These controls record product configuration and do not verify legal tax status.

The server calculates gross price, coupon and other discounts, net before tax, tax, final total, customer credit, and finally the external payment amount. Money uses integer minor units and tax rates use basis points; browser previews are informational.

Coupon management reuses Finance → Coupons and the existing coupon model. A coupon belongs to one organization. Authorized club administrators may create, update, archive, review, and redeem their own organization's coupons, but not a parent or sibling coupon. Coupon discounts reduce net sales and are not expenses. Each redemption snapshots the coupon configuration and actual discount.

Finance terminology is intentionally distinct:

• Refund returns money through the supported original payment method and is capped at the unrefunded paid amount.
• Customer credit is a future-use liability for one customer, organization, and currency; only the amount remaining after credit is sent to the payment provider.
• Invoice credit document remains owned by the configured invoice provider and links back to the original invoice.
• Manual credit adjustment requires finance authorization, a reason, an immutable balance entry, and an audit event.

Money-moving actions require confirmation and idempotency. Retrying the same request returns the existing result. Historical records without safely derivable amounts remain visible but require reconciliation before refund or credit issuance.

Imported Old IKC source controls appear only when the active organization hierarchy has imported IKC payment history. Other organizations receive new-system financial records only, and the API rejects an unavailable IKC source.

Coverage references:

• Knowledge base

Dog ancestor counts runbook

This covers /[locale]/admin/metrics/dog-ancestor-counts.

What this feature stores

• dog_ancestor_counts Shared lineage fact table used by pedigree search and smart mating.
• dog_ancestor_metrics Admin-facing searchable summary built from dog_ancestor_counts.

The admin page reads only from precomputed structures. It does not run recursive pedigree traversal on request.

Counting rules

For one dog:

• each valid sire/dam path contributes one occurrence
• duplicate appearances through multiple valid paths count multiple times
• each stored row tracks:
  • ancestor_id
  • gen
  • side
  • occ
• cycles are ignored by path protection in the recursive query
• missing parents stop traversal naturally

Smart search behavior

The admin smart search matches against:

• dog name
• normalized dog name
• legacy ID
• kennel registration number
• aggregated ancestor names

It uses indexed tsvector and trigram fields from dog_ancestor_metrics, so searching the admin page does not hit recursive lineage queries.

Why the old rebuild was failing

The earlier design tried to:

• rebuild a full build table
• checkpoint the run
• swap tables at the end

That caused repeated operational failures because the final promotion path still relied on large locks and long-running bulk work on a busy production database. The observed failure modes were:

• statement timeouts
• stale active-run state after interrupted workers
• production risk during final promotion

New safe model

The replacement design is async and resumable:

1. schema migration creates summary, queue, dirty-event, run, and batch tables
2. a trigger on dogs only marks records dirty
3. the worker expands dirty roots into impacted descendants
4. queue rows are claimed in bounded batches with leases
5. one dog is recomputed per short transaction
6. dog_ancestor_metrics is refreshed from dog_ancestor_counts

No heavy backfill runs inside a schema migration or page request.

Freshness model

A row is stale when:

• it is queued for recompute
• it has no logic version yet
• its logic version is behind the current runtime logic version

Supported update paths

• new dog inserted trigger writes a dirty event, worker queues recompute
• sire/dam changed trigger writes pedigree_change, worker expands descendants and requeues impacted dogs
• searchable dog fields changed trigger writes search_field_change, worker refreshes search summary
• admin single-dog recompute page action queues one dog
• selection recompute page action queues a selected set
• full rebuild page or CLI creates a run, worker enqueues published dogs in chunks, then processes queue items incrementally

Safe commands

Queue a full rebuild:

npm run ancestry:rebuild -- --mode=full --initiated-by=<your-name> --max-gen=6

Queue a summary backfill:

npm run ancestry:rebuild -- --mode=summary --initiated-by=<your-name>

Run one maintenance cycle:

npm run ancestry:maintain -- --initiated-by=<your-name> --event-batch=25 --summary-batch=100 --recompute-batch=25 --lease-seconds=120

Run the continuous worker:

npm run ancestry:worker -- --initiated-by=<your-name> --event-batch=25 --summary-batch=100 --recompute-batch=25 --sleep-ms=1500

Inspect status:

npm run ancestry:status

Clear a stuck run safely:

npm run ancestry:clear -- --run-id=<run-uuid>

Operational warnings

• never run heavy backfills in schema migrations
• never trigger full recompute from a page load or API request path
• keep batch sizes conservative in production first
• if logic changes, bump the logic version on the next full recompute

Verification checklist

Small sample:

• queue a single-dog recompute
• verify the dog appears in admin search by dog name and ancestor name

Larger sample:

• queue a full recompute
• run the worker with conservative batch sizes
• verify page responses stay responsive while batches progress

Failure and restart:

• start a full run
• stop the worker mid-run
• restart the worker
• verify the queue resumes and progress continues

Freshness:

• edit a dog pedigree
• verify stale/queued state appears on the admin page
• run the worker
• verify the row returns to fresh

Need help improving this guide?

If this page is unclear, outdated, or missing a real user path:

• Take a screenshot
• Copy the page URL
• Describe what you expected vs what happened

Send it to [email protected].