# Person and Connection Data Management

This document describes the patterns for managing person profiles and professional network connection data for heritage custodian staff.

---

## Overview

The GLAM project tracks people associated with heritage custodian institutions:
- **Staff members** (curators, archivists, directors, researchers)
- **Their professional networks** (LinkedIn connections in heritage sector)
- **Cross-custodian relationships** (people who work at multiple institutions)

All person data is stored in `data/custodian/person/` with strict file naming conventions.

---

## File Types

### 1. Person Profile Files

**Purpose**: Store comprehensive professional profile data for an individual

**Naming Convention**: `{linkedin-slug}_{ISO-timestamp}.json`

**Examples**:
```
alexandr-belov-bb547b46_20251210T120000Z.json
giovanna-fossati_20251209T170000Z.json
```

**Contents**:
- Full career history with dates and durations
- Education history
- Skills and endorsements
- About section text
- Heritage-relevant experience tags
- Profile image URL
- Extraction metadata

### 2. Connection Files

**Purpose**: Store all professional connections for a person with network analysis

**Naming Convention**: `{linkedin-slug}_connections_{ISO-timestamp}.json`

**Examples**:
```
alexandr-belov-bb547b46_connections_20251210T160000Z.json
giovanna-fossati_connections_20251211T140000Z.json
```

**Contents**:
- All connections with degree (1st, 2nd, 3rd+)
- Heritage relevance classification
- Heritage type codes (GLAMORCUBESFIXPHDNT)
- Organization affiliations
- Geographic distribution
- Network analysis and insights

---

## Directory Structure

```
data/custodian/
├── person/                              # All person data files
│   ├── alexandr-belov-bb547b46_20251210T120000Z.json        # Profile
│   ├── alexandr-belov-bb547b46_connections_20251210T160000Z.json  # Connections
│   ├── giovanna-fossati_20251209T170000Z.json               # Profile
│   ├── giovanna-fossati_connections_20251211T140000Z.json   # Connections
│   └── ...
├── NL-NH-AMS-U-EFM-eye_filmmuseum.yaml  # Custodian referencing person files
└── ...
```

---

## Referencing Person Data from Custodian Files

### Basic Reference (Profile Only)

```yaml
collection_management_specialist:
- name: Alexandr Belov
  role: Collection/Information Specialist
  linkedin_url: https://www.linkedin.com/in/alexandr-belov-bb547b46
  current: true
  person_profile_path: data/custodian/person/alexandr-belov-bb547b46_20251210T120000Z.json
```

### Full Reference (Profile + Connections)

```yaml
collection_management_specialist:
- name: Alexandr Belov
  role: Collection/Information Specialist
  linkedin_url: https://www.linkedin.com/in/alexandr-belov-bb547b46
  current: true
  person_profile_path: data/custodian/person/alexandr-belov-bb547b46_20251210T120000Z.json
  person_connections_path: data/custodian/person/alexandr-belov-bb547b46_connections_20251210T160000Z.json
```

---

## Heritage Type Codes

Use single-letter GLAMORCUBESFIXPHDNT codes for `heritage_type` field:

| Code | Type | Description |
|------|------|-------------|
| G | Gallery | Art gallery or exhibition space |
| L | Library | Library (public, academic, specialized) |
| A | Archive | Archive (government, corporate, personal) |
| M | Museum | Museum (art, history, science, etc.) |
| O | Official institution | Government heritage agencies |
| R | Research center | Research institutes and documentation centers |
| C | Corporation | Corporate heritage collections |
| U | Unknown | Type cannot be determined |
| B | Botanical/Zoo | Botanical gardens and zoological parks |
| E | Education provider | Educational institutions with collections |
| S | Collecting society | Societies collecting specialized materials |
| F | Features | Physical landscape features with heritage significance |
| I | Intangible heritage | Organizations preserving intangible heritage |
| X | Mixed types | Multiple types |
| P | Personal collection | Private personal collections |
| H | Holy sites | Religious heritage sites and institutions |
| D | Digital platform | Digital heritage platforms and repositories |
| N | NGO | Non-governmental heritage organizations |
| T | Taste/smell | Culinary and olfactory heritage institutions |

---

## Network Analysis Sections

Connection files should include analysis sections:

### `network_analysis`

Aggregate statistics:
- Total connections extracted
- Heritage-relevant count and percentage
- Connections by heritage type
- Connections by degree (1st, 2nd, 3rd+)
- Key organizations
- Geographic distribution
- Mutual connection hubs

### `heritage_network_insights`

Strategic analysis:
- Primary clusters (institutional groupings)
- Career network trace (where network was built)
- Strategic value summary

---

## Use Cases

### 1. Staff Discovery

Find all people associated with a heritage custodian:
- Query custodian files for `person_profile_path` references
- Aggregate by institution

### 2. Cross-Custodian Relationships

Find people who work at multiple institutions:
- Analyze career history across profiles
- Identify shared connections

### 3. Heritage Sector Network Mapping

Build a graph of heritage professionals:
- Nodes: People with heritage_relevant=true
- Edges: Connection relationships
- Clusters: Organizations and institutions

### 4. Expertise Discovery

Find specialists in a domain:
- Search career history for keywords
- Filter by heritage type codes
- Sort by network centrality

---

## Related Documentation

- **AGENTS.md Rule 12**: Person Data Reference Pattern
- **AGENTS.md Rule 14**: Exa MCP LinkedIn Profile Extraction
- **AGENTS.md Rule 15**: Connection Data Registration
- `.opencode/PERSON_DATA_REFERENCE_PATTERN.md`: Full pattern documentation
- `.opencode/CONNECTION_DATA_REGISTRATION_RULE.md`: Connection file structure
- `.opencode/EXA_LINKEDIN_EXTRACTION_RULES.md`: LinkedIn extraction rules

---

## Implementation Reference

**Reference Example (Profile)**: `data/custodian/person/alexandr-belov-bb547b46_20251210T120000Z.json`

**Reference Example (Connections)**: `data/custodian/person/alexandr-belov-bb547b46_connections_20251210T160000Z.json`

**Custodian Example**: `data/custodian/NL-NH-AMS-U-EFM-eye_filmmuseum.yaml`

---

*Last Updated: 2025-12-11*