Barkday Project Governance & Data Update Guide
Purpose & Vision
Barkday exists to celebrate every dog's next birthday and to use that milestone as a positive teaching opportunity. Beyond simply converting a canine's age into "dog years," the app delivers breed-specific care guidance, training games, enrichment suggestions, and gentle reminders that evolve as a dog moves through life. By surfacing the very real differences between breeds-energy needs, guardian instincts, coat care, health risks, etc.-we help guardians make better day-to-day decisions, improving dogs' well-being around the world. The educational content in Barkday is not veterinary advice; it should always be paired with a disclaimer to consult a veterinarian for specific medical concerns.
The platform also offers optional links to gift ideas. Gift panels are hidden by default; users only see affiliate recommendations if they choose to explore them. This keeps the primary purpose on education rather than commerce. The affiliate revenue is meant to offset development costs, not to compromise trust.
Data File Overview
Barkday's personalization engine relies on a small set of structured JSON files. Each serves a distinct role and should be updated carefully:
File
Role
Key fields
breed_aliases.json
Maps common misspellings, local names, and abbreviations back to a canonical breed name. This enables search and free-text entry to "just work."
Top-level keys are canonical breed names; values are lists of strings. Meta keys beginning with _ (e.g., _dataset_id) are reserved.
breed_taxonomy.json
Provides high-level classification for each breed. It specifies an akc_group (or the closest functional group) and a list of clusters describing behaviour, physiology, coat, etc. Optional meta_groups_hint can tag breeds for umbrella group pages.
Keys are breed names; each value has an akc_group string and a clusters array. See clusters defined in the rules library.
breed_groups.json
Defines umbrella groups displayed in the UI (e.g., "Working / Herding", "Terriers"). Each entry lists example breeds, core traits, enrichment ideas, owner tips, a short notification line, cautions, and gift tags. Groups are additive; new ones can be added without impacting existing logic.
It is an array of objects. Each object has an id, name, examples, core_traits, enrichment, owner_tips, notification_short, cautions, and gift_tags.
reco-breed.json
Provides breed-specific overrides across "lanes" (training, health, exercise, bonding, gear, nutrition) for specific age markers. When a breed is not listed, defaults cascade from clusters and general rules.
The root object has a breeds property; each breed can define one or more age keys (e.g., "2", "7", "12"). Each age contains a lanes object with lists of bullet points.
reco-banded.json
Stores fully materialised recommendations for each breed across age "bands" (puppy, young, adult, senior). Most entries are currently empty. When filled, these will override cluster-based defaults for the entire age range.
bands ? band names ? breed names ? lanes.
rules_library.json
Houses curated rule fragments keyed by selectors such as akc_group, clusters, or other tags. Each rule defines which age bands it applies to and per-lane bullet lists. This file acts as a toolbox of reusable guidance and can be expanded safely.
Contains a defaults object with baseline lanes, and a rules array. Rules should be non-conflicting; more specific selectors take precedence.
Governance Principles & Workflow
1. Major vs Minor Updates
2. Major push: When adding or refactoring many breeds or structural metadata, bundle all changes into a single coordinated release. Updating aliases, taxonomy, groups, and overrides together minimises transient states that could break search or recommendations. Always increment the query-parameter version (?v=) for each updated file in app.js to bust caches.
3. Minor fixes: Typo corrections, adding a single alias, or adjusting a bullet can be applied ad-hoc. These should not remove existing content unless it is clearly erroneous. Avoid regressing the richness of data-placeholders should always be replaced with substantive guidance rather than deleted.
4. Adding a New Breed
5. Research. Collect data from reputable, primary sources such as breed registries, veterinary bodies, or peer-reviewed literature. Identify the breed's original purpose, temperament, exercise needs, coat type, and health considerations. For example, the Kangal is a traditional Turkish livestock guardian used to protect sheep from wolves, while the Thai Ridgeback is a primitive pariah-type dog with high prey drive and independent temperament[1].
6. Alias mapping. Append synonyms, local names, and abbreviations to breed_aliases.json. Do not duplicate canonical keys. Use consistent capitalisation for keys, but preserve local casing in alias lists (e.g., "Kangal Çoban Köpeği").
7. Taxonomy. Add an entry to breed_taxonomy.json with the closest akc_group (or FCI/FSS approximation) and an appropriate set of clusters. Reuse existing clusters where possible (e.g., guardian_protection, independence_high, prey_drive_high, coat_double, muzzle_brachy). If a new behavioural phenotype emerges across multiple breeds, propose a new cluster via the rules library.
8. Group assignment. If the breed belongs to an umbrella group already defined in breed_groups.json, there is nothing to do. Otherwise, either extend an existing group's examples list or create a new group entry. New groups must include all fields (examples, core traits, enrichment, tips, etc.) to avoid UI gaps.
9. Breed-specific overrides. Only create entries in reco-breed.json when a breed's needs differ materially from its clusters. Use specific, actionable bullet points. Keep lane names consistent (training, health, exercise, bonding, gear, nutrition). Omitting a lane or age means the defaults will apply.
10. Banded recommendations. Populate reco-banded.json for breeds that warrant broad, multi-age guidance. For many breeds it suffices to rely on the rules library; banded overrides should be used sparingly to avoid duplication.
11. Version bump. Update the version query in app.js for any modified file (e.g., breed_aliases.json?v=2). This ensures users download the new data.
12. Data Quality Standards
13. Comprehensiveness. Avoid leaving "blank" guidance. If a lane is empty, inherit from clusters or defaults; only override when you have high-confidence, breed-specific advice. Never cut existing content to shorten an entry-replace it with richer, evidence-based recommendations.
14. Consistency. Use the same grammatical style across bullet points (present-tense commands; second-person point of view). Keep lists short (typically 2-4 bullets) and actionable.
15. Attribution. When deriving cluster assignments or traits from external sources, capture the justification in internal comments or commit messages. For example, the Africanis is a landrace dog shaped by natural selection and exhibits watchful territorial behaviour with high survival instincts[2]; this supports classifying it as independent and guardian oriented.
16. Localization. The dataset should remain culturally neutral. Do not embed region-specific advice or brand names in the core guidance. Gift tags can be mapped to different marketplaces through the affiliate configuration.
17. Monetization & Ethics
18. Gift recommendations must be additive and optional. They should never replace or obscure care guidance. Mark affiliate links clearly within the hidden gift panel, and include an earnings disclaimer as required by law.
19. Avoid promoting products that could harm dogs or contradict veterinary best practices.
20. Memory Reset & Usage of this Document
21. In some tool environments, memory may reset between messages. Save this guidance file (guidance.md) in your working directory and refer to it before making any proposal. The presence of this file should prevent accidental truncation of data or schema misunderstandings.
22. When uncertain, err on the side of more detail and preserve prior work. Never drop existing bullet lists without a strong reason and a better replacement.
Example Expansion: International Guardians & Pariah Types
Below is a template illustrating how to add two umbrella groups and a handful of breeds. Adapt names, clusters, and examples as needed.
A. New umbrella groups (breed_groups.json)
[
  // ... existing group entries ...,
  {
    "id": "international_guardian",
    "name": "International Guardian Breeds",
    "examples": ["Kangal", "Caucasian Shepherd Dog", "Central Asian Shepherd Dog", "Boerboel", "Spanish Mastiff"],
    "core_traits": [
      "Livestock guardians with strong protective instincts",
      "Independent decision makers; thrive on space and clear boundaries",
      "Large/giant breeds requiring steady, confident handling"
    ],
    "enrichment": [
      "Calm patrol walks or perimeter scent searches",
      "Boundary and neutrality training with structured greetings",
      "Puzzle feeders and low-impact nosework to satisfy problem-solving drives"
    ],
    "owner_tips": [
      "Provide secure fencing and defined territories; avoid leaving unattended with strangers",
      "Early socialization is crucial-introduce new people and animals gradually",
      "Use positive reinforcement and patient leadership; harsh corrections erode trust"
    ],
    "notification_short": "Reinforce calm neutrality with a patrol or scent game today.",
    "cautions": [
      "Can be aloof or reactive to perceived threats; manage interactions carefully",
      "Heat sensitivity and joint stress are concerns for heavy breeds"
    ],
    "gift_tags": ["training", "scent", "puzzle", "place_mat", "cooling_mat"]
  },
  {
    "id": "village_landrace_type",
    "name": "Pariah / Landrace Types",
    "examples": ["Thai Ridgeback", "Canaan Dog", "Carolina Dog", "Africanis"],
    "core_traits": [
      "Primitive dogs shaped by natural selection; highly intelligent and alert",
      "Independent with strong survival and prey drives",
      "Bond deeply with family but remain reserved with strangers"
    ],
    "enrichment": [
      "Scent work and foraging games to channel instincts",
      "Long-line hikes or safe off-lead exploration in secure areas",
      "Recall and engagement games focusing on voluntary check-ins"
    ],
    "owner_tips": [
      "Use positive reinforcement to build trust; avoid coercive methods",
      "Provide robust containment (secure fencing, long lines) to prevent wandering",
      "Socialize early but avoid overwhelming environments; allow choice and control"
    ],
    "notification_short": "Plan a scent game and recall session to harness that primitive drive.",
    "cautions": [
      "High prey drive-manage small animals and wildlife encounters",
      "May not thrive in dense urban settings without ample outlets"
    ],
    "gift_tags": ["scent", "foraging", "long_line", "puzzle"]
  }
]
B. Breed aliases (breed_aliases.json)
{
  // ... existing meta keys and breeds ...,
  "Kangal": ["Kangal Shepherd", "Turkish Kangal", "Kangal Çoban Köpeği"],
  "Central Asian Shepherd Dog": ["Central Asian Ovcharka", "CASD", "Alabai"],
  "Caucasian Shepherd Dog": ["Caucasian Ovcharka", "Caucasian Mountain Dog"],
  "Boerboel": ["South African Mastiff", "Boerbull", "Boerboel Dog"],
  "Spanish Mastiff": ["Mastín Español", "Spanish Mastin"],
  "Thai Ridgeback": ["TRD", "Mah Thai Lung Ahn"],
  "Canaan Dog": ["Israeli Canaan", "Canaan", "Kelev K'naani"],
  "Carolina Dog": ["American Dingo", "Dixie Dingo", "Carolina Dingo"],
  "Africanis": ["Africanis Dog", "African Dog", "Bantu Dog"]
}
C. Taxonomy entries (breed_taxonomy.json)
{
  // ... existing breeds ...,
  "Kangal": {
    "akc_group": "Working",
    "clusters": ["guardian_protection", "independence_high"],
    "meta_groups_hint": ["International-guardian"]
  },
  "Central Asian Shepherd Dog": {
    "akc_group": "Working",
    "clusters": ["guardian_protection", "independence_high", "coat_double", "coat_shed_heavy"],
    "meta_groups_hint": ["International-guardian"]
  },
  "Caucasian Shepherd Dog": {
    "akc_group": "Working",
    "clusters": ["guardian_protection", "independence_high", "coat_double", "coat_shed_heavy", "climate_heat_sensitive"],
    "meta_groups_hint": ["International-guardian"]
  },
  "Boerboel": {
    "akc_group": "Working",
    "clusters": ["guardian_protection", "bulldog_molosser", "independence_high", "chew_power"],
    "meta_groups_hint": ["International-guardian"]
  },
  "Spanish Mastiff": {
    "akc_group": "Working",
    "clusters": ["guardian_protection", "bulldog_molosser", "independence_high"],
    "meta_groups_hint": ["International-guardian"]
  },
  "Thai Ridgeback": {
    "akc_group": "Hound",
    "clusters": ["sight_hound", "prey_drive_high", "independence_high"],
    "meta_groups_hint": ["Village/Landrace/Type"]
  },
  "Canaan Dog": {
    "akc_group": "Herding",
    "clusters": ["guardian_protection", "prey_drive_high", "independence_high"],
    "meta_groups_hint": ["Village/Landrace/Type"]
  },
  "Carolina Dog": {
    "akc_group": "Hound",
    "clusters": ["sight_hound", "prey_drive_high", "independence_high"],
    "meta_groups_hint": ["Village/Landrace/Type"]
  },
  "Africanis": {
    "akc_group": "Hound",
    "clusters": ["guardian_protection", "prey_drive_high", "independence_high"],
    "meta_groups_hint": ["Village/Landrace/Type"]
  }
}
D. Breed-specific overrides (reco-breed.json)
Only include ages and lanes where the general rules do not suffice. Below is a minimal example for two breeds to illustrate the structure; expand as data becomes available.
{
  "breeds": {
    // ... existing breeds ...,
    "Kangal": {
      "ages": {
        "12": {
          "lanes": {
            "training": [
              "Neutrality > friendliness: reward calm observation of strangers",
              "Teach solid boundary cues (backyard perimeter, 'place' mat)"
            ],
            "exercise": [
              "Long, slow patrol walks (45-60 min) plus mental scent games",
              "Avoid repetitive fetch; focus on varied terrain and nosework"
            ],
            "health": [
              "Monitor joints; avoid jumping until growth plates close",
              "Heat management in summer; provide shade and water"
            ]
          }
        },
        "36": {
          "lanes": {
            "training": [
              "Maintain neutrality training; practice controlled greetings with visitors",
              "Introduce advanced scent discrimination games to mimic patrol duties"
            ],
            "exercise": [
              "Daily patrol or perimeter walk (60+ min) with decompression sniff time"
            ],
            "gear": [
              "Well-fitted Y-harness; sturdy long line for field scent games",
              "Cooling mat in warm months"
            ]
          }
        }
      }
    },
    "Thai Ridgeback": {
      "ages": {
        "12": {
          "lanes": {
            "training": [
              "High-value recall games; long-line play in safe areas",
              "Trick chaining (spin ? down ? touch) to engage independent mind"
            ],
            "exercise": [
              "Daily sprints (5-10 min) in fenced area + decompression walks",
              "Foraging and scent puzzles on rest days"
            ],
            "bonding": [
              "Massage and cooperative care sessions to build trust",
              "Interactive toy play to satisfy prey drive"
            ]
          }
        }
      }
    }
  }
}
Final Notes
This guide is meant to be an evolving reference. As you continue to refine Barkday's data, append new clusters, breeds, and rules in a way that always adds value and never removes richness. Use versioned data files and treat major changes as coordinated releases. Above all, remember that your work directly influences how guardians care for their dogs; accuracy and compassion matter.

[1] Thai Ridgeback - Wikipedia
https://en.wikipedia.org/wiki/Thai_Ridgeback
[2] Africanis - Dog of Africa
https://sa-breeders.co.za/org/africanis/index.htm