arkavo-org/app

Create comprehensive ERD documentation and model diagrams

Ouverte

#153 ouverte le 26 oct. 2025

 (0 commentaire) (0 réaction) (0 personne assignée)Swift (0 fork)auto 404
documentationgood first issue

Métriques du dépôt

Stars
 (0 étoile)
Métriques de merge PR
 (Aucune PR mergée en 30 j)

Description

Problem

SwiftData model relationships and structure are not well documented:

  • No Entity-Relationship Diagram (ERD)
  • No visual representation of model relationships
  • Difficult for new contributors to understand data model
  • No documentation of delete rules and cascading behavior

Proposed Documentation

1. Create ERD Diagram

Create docs/ERD.md with Mermaid diagram showing:

  • All entities (Account, Profile, Stream, Thought, BlockedProfile)
  • Relationships and cardinality
  • Delete rules (cascade, nullify)
  • Unique constraints
  • External storage attributes

2. Create Model Documentation

Create docs/MODELS.md with:

  • Detailed description of each model
  • Property descriptions
  • Relationship explanations
  • Usage examples
  • Common pitfalls

3. Safe Access Patterns

Document safe vs unsafe patterns:

DO:

// Use computed properties that filter deleted objects
let validThoughts = stream.validThoughts

// Check before accessing optional relationships
if let source = stream.safeSource {
    // source is guaranteed to be valid
}

DON'T:

// Direct access without checking isDeleted
let mediaType = stream.source?.metadata.mediaType  // ⚠️ May crash!

Implementation Checklist

  • Create docs/ERD.md with Mermaid diagram
  • Create docs/MODELS.md with detailed docs
  • Add inline documentation to model files
  • Create docs/SWIFTDATA_GUIDELINES.md
  • Update CONTRIBUTING.md with data model section
  • Add examples of safe vs unsafe patterns
  • Document migration process
  • Add troubleshooting guide

Files to Create

  • docs/ERD.md
  • docs/MODELS.md
  • docs/SWIFTDATA_GUIDELINES.md

Files to Modify

  • CONTRIBUTING.md
  • README.md (add link to data model docs)

Guide contributeur