Skip to content

REPOSITORY_STRUCTURE.md

Latest commit

 

History

History
99 lines (69 loc) · 4.76 KB

REPOSITORY_STRUCTURE.md

File metadata and controls

99 lines (69 loc) · 4.76 KB

Repository Structure Best Practices

This document explains the repository structure and why files are organized this way.

Directory Structure

.github/ - GitHub-Specific Configuration

  • Purpose: Contains GitHub Actions + CI-only helpers
  • Contents:
    • workflows/ - Actions definitions (check-docs-updates.yml, tests.yml, pre-commit.yml)
    • scripts/validate_docs_structure.py - Lightweight CI validation helper
    • docs-version-*.json - Metadata files used by historic workflows
    • CI note: check-docs-updates.yml auto-creates the chore/sync-affinity-docs branch/PR and then explicitly triggers tests.yml and pre-commit.yml via workflow_dispatch so that required checks run even though the PR is opened by a workflow.

Why here?: Keeps automation-specific assets scoped to GitHub configuration.

tests/ - Test Files

  • Purpose: Contains all test scripts and test-related files
  • Contents:
    • Test scripts (.sh, .py)
    • Test documentation (README.md)

Why here?: Standard practice - test files belong in a tests/ directory at the repository root, not in .github/.

docs/development/ - Development Documentation

  • Purpose: Documentation for developers working on the project
  • Contents:
    • TESTING.md - Testing guide
    • TEST_RESULTS.md - Test results summary

Why here?: Development documentation belongs in docs/, separate from user-facing documentation.

docs/v1/ and docs/v2/ - Generated Documentation Outputs

  • Purpose: Houses generated artifacts that mirror the official Affinity API documentation.
  • Key files:
    • docs/v1/affinity_api_docs.md – generated by tools/v1_sync_pipeline/sync_v1_docs.py
    • docs/v2/affinity_api_docs.md – generated by tools/v2_sync_pipeline/sync_v2_docs.py
    • docs/v2/openapi.json – generated by tools/v2_sync_pipeline/sync_v2_docs.py (stable OpenAPI download)

Why here?: These are the canonical, committed outputs of the sync pipelines. They should never be edited manually.

tools/v1_sync_pipeline/ - Production Sync + QA Tooling

  • Purpose: Houses the production-ready sync pipeline and QA scripts
  • Contents:
    • sync_v1_docs.py – Fetches live HTML, renders markdown, writes metadata
    • qa/check_links.py – Anchor/external link validation
    • qa/compare_to_live.py – Manual comparison helper for browser snapshots

Why here?: Separates long-lived automation from discarded extraction experiments (scripts/ directory has been removed).

tools/v2_sync_pipeline/ - Production v2 Sync Pipeline

  • Purpose: Fetches the Redocly state payload from https://developer.affinity.co/ and generates the v2 markdown mirror + a stable OpenAPI JSON artifact.
  • Contents:
    • sync_v2_docs.py – Fetches Redoc shell HTML + state JS, extracts OpenAPI JSON, renders markdown, writes outputs under docs/v2/
    • openapi_loader.py – Discovers the redocly-state-*.js asset and extracts the embedded OpenAPI document
    • markdown_renderer.py – Converts the OpenAPI spec into readable markdown sections + appendices

Why here?: Keeps v2 automation co-located with v1, using the same “generated outputs, never hand-edit” approach.

requirements-ci.txt - CI Dependencies

  • Purpose: Python dependencies needed for CI/CD workflows
  • Location: Repository root

Why here?: Standard practice—requirements files sit at the root and make it easy for workflows to install dependencies.

tmp/ - Generated Artifacts (Gitignored)

  • Purpose: Holds HTML snapshots, extracted code blocks, and comparison reports generated by the sync pipeline
  • Behavior: Listed in .gitignore; contents are safe to delete/regenerate

Why here?: Keeps transient data out of version control while giving engineers a predictable place to inspect intermediate outputs.

Best Practices Followed

  1. ✅ Tests in tests/ - Not in .github/
  2. ✅ Documentation in docs/ - Organized by purpose
  3. ✅ Requirements at root - Standard location
  4. ✅ GitHub configs in .github/ - GitHub-specific files
  5. ✅ Clear separation - Each directory has a clear purpose

File Locations Summary

File Type Location Reason
Test scripts tests/ Standard practice
Test docs docs/development/ Development docs
CI scripts .github/scripts/ GitHub-specific (only validate_docs_structure.py remains)
Sync pipeline tools/v1_sync_pipeline/ Production automation + QA helpers
Sync pipeline (v2) tools/v2_sync_pipeline/ Production automation for v2 docs
Workflows .github/workflows/ GitHub Actions
Requirements requirements-ci.txt Root level, CI-specific
Metadata .github/docs-version-*.json Workflow state