data-architecture

---
name: data-architecture
description: Generate data architecture and persistence layer documentation with data model diagram
license: MIT
---

# Data Architecture & Persistence Layer

Analyze the project to document database configuration, entity models, data ownership boundaries, repository interfaces, and caching strategies. Generate a Mermaid ER diagram showing entity relationships. Save to `.github/modernize/assessment/engines/facts/data-architecture.md`.

## Input Parameters

- `workspace-path` (optional): Path to the project to analyze (defaults to current directory)

## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block

Mermaid `erDiagram` has a stricter grammar than flowchart. One bad attribute line or one stray `{` crashes the **whole** diagram with `Syntax error in text`. Stay strictly inside this subset:

1. **Chart kind.** `erDiagram` only.
2. **Attribute grammar — exact shape.** Every attribute line inside an entity body MUST match:

   ```
   <type> <name> [<key>] ["<description>"]
   ```

   - `<type>` / `<name>`: single tokens, plain text (letters, digits, underscore). No spaces, no backticks, no `@#$%&`.
   - `<key>`: optional. **Exactly one of** `PK`, `FK`, `UK` — never two, never combined. Compound tokens like `PK_FK`, `PKFK`, `PK/FK` crash the parser.
   - `<description>`: optional, must be a double-quoted string on one line. Free text, but obey rule 4.
3. **Relationships.** `<EntityA> <leftCard>--<rightCard> <EntityB> : "label"`. Each side independently picks `||` (exactly one), `|o`/`o|` (zero or one), `}o`/`o{` (zero or many), or `}|`/`|{` (one or many). The open side of `o`/`}`/`{` faces inward toward `--`. Always quote the label.
4. **Banned characters inside any quoted description or relationship label:**

   | Banned | Why it breaks | Replacement |
   |---|---|---|
   | `\n` (literal two chars) | escape removed | drop, or shorten |
   | `{` `}` | opens an entity block | use `<...>` for placeholders, e.g. `"Redis key /basket/<BuyerId>"` |
   | `"` (a second double-quote) | closes description early | `'` (single quote) |
   | `` ` `` (backtick) | not part of grammar | drop |
   | `—` `–` (em/en dash) | parser may treat as edge | `-` (ASCII hyphen) |
   | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` |
   | `@` `#` `$` `%` `&` | unsafe in names/descriptions | rephrase or drop |

5. **Composite PK that is also FK.** Mark every column as `PK` only and note the FK role inside the quoted description. The FK relationship is already shown by the cardinality arrow — duplicating it as a second key marker crashes the parser.

### Canonical attribute examples (copy these shapes)

```
int        Id              PK
string     Name
int        OwnerId         FK
int        InstructorId    PK    "also FK to Person (shared PK)"
int        CourseId        PK    "composite PK; FK to Course"
int        StudentId       PK    "composite PK; FK to Person"
string     Email           UK    "unique"
decimal    Budget                "money column"
bytes      RowVersion            "concurrency token"
```

### Mandatory self-attestation

Immediately before writing the ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation):

```
<!-- mermaid-checked: every attribute is `<type> <name> [<key>] ["<description>"]` with at most one of PK/FK/UK, no \n in descriptions, no {} in descriptions, every relationship label is double-quoted -->
```

If you cannot truthfully emit that comment, fix the diagram first.

---

## Scope Boundaries — Avoid Redundancy with Other Skills

This skill is part of a set of four complementary assessment skills. To avoid content duplication across their output documents, observe these scope rules:

- **Introduction**: Write a 1-2 sentence intro focused on the data layer (number of entities, database types, ORM). Do NOT restate the application's overall architecture type, web framework, or API surface — those are covered by other skills.
- **Configuration property keys/values** (e.g., `spring.jpa.hibernate.ddl-auto`, `spring.sql.init.*`) are owned by the `configuration-inventory` skill. In the Database Configuration table, describe the *behavior* (e.g., "Hibernate does not manage schema; SQL scripts are authoritative") but do NOT list raw property key-value pairs. Reference `configuration-inventory.md` for the full property inventory.
- **API endpoints and HTTP methods** are owned by the `api-service-contracts` skill. Do NOT list controller endpoints or HTTP paths. Repository methods are in scope for this skill; controller routes are not.
- **Business workflow steps and validation rules** are owned by the `business-workflows` skill. Do NOT describe multi-step business processes or enumerate validation constraints. When documenting entity relationships (cascade, fetch), focus on the persistence/ORM implications, not the business process flow.
- **Deployment configurations** (Docker Compose, K8s, profiles) are owned by the `configuration-inventory` skill. Mention database profiles only in the Database Configuration table to identify which DB is used per profile — do NOT describe Docker Compose services, K8s manifests, or deployment targets in detail.

## Execution Steps

### Step 1: Generate Database Configuration Section

Extract database configuration from project files, **per profile/environment**, and produce the complete `## Database Configuration` section:

- Database types: HSQLDB, MySQL, PostgreSQL, MongoDB, SQL Server, Oracle, SQLite, CosmosDB, DynamoDB
- **Per-profile configuration**: identify which database is used in each profile (e.g., HSQLDB for `default`/dev in-memory testing, MySQL for `production`/`mysql` profile)
- Database drivers per profile (e.g., `mysql-connector-java` for production, `hsqldb` for development)
- Connection configuration: connection strings, JDBC URLs, pooling settings (HikariCP, connection pool size)
- Migration tools: Flyway, Liquibase, EF Migrations, Alembic, Prisma Migrate, Knex migrations
- Schema management: DDL auto-generation settings (`spring.jpa.hibernate.ddl-auto`), schema versioning, initial schema scripts
- Seed data: `data.sql`, `import.sql`, seed migration files, or programmatic data seeding

### Step 2: Generate Data Ownership per Service Section

Determine table/entity ownership across modules/services and produce the complete `## Data Ownership per Service` section. Scope is strictly the per-service ownership table — high-level data boundary discussion belongs in Step 6.

For each module/service, identify:

- Which tables/entities it owns (bounded context analysis)
- ORM framework used (e.g., Hibernate, EF Core, MyBatis, Mongoose)
- Caching layer used by this service (if any)
- Brief notes (e.g., outbox table, schema-per-service)

> Do NOT include shared-vs-isolated data store summary, cross-service data access patterns, or read/write/CQRS observations here — those belong in the `## Data Ownership Boundaries` section (Step 6).

### Step 3: Generate Entity Model Section

Scan source code for data access patterns and ORM entities, then produce the complete `## Entity Model` section:

**Analysis:**
- Java: JPA/Hibernate entities (`@Entity`, `@Table`), Spring Data repositories (`JpaRepository`, `CrudRepository`), MyBatis mappers, JDBC templates
- .NET: EF Core `DbContext`, EF Core entities, Dapper, ADO.NET
- JavaScript/TypeScript: Mongoose models/schemas, Sequelize models, TypeORM entities, Prisma schema, Knex migrations

Identify:
- Entity/model classes with their fields, types, and constraints — note the source file path for each entity
- Transaction management annotations/configuration (`@Transactional`, `TransactionScope`, etc.)
- Bidirectional vs unidirectional relationship mappings (e.g., `owner.addPet(pet)` establishing parent-child links)

**Diagram — Mermaid `erDiagram`:**
- Show primary entities with key fields (PK, FK)
- Use standard cardinality notation: `||--o{` (one-to-many), `||--||` (one-to-one), `}o--o{` (many-to-many)
- Group related entities logically
- Include relationship labels
- Annotate which service owns each entity group (use comments or subgraph labels)

Reference example (this block satisfies every Safety Constraint — match its shape):

<!-- mermaid-checked: every attribute is `<type> <name> [<key>] ["<description>"]` with at most one of PK/FK/UK, no \n in descriptions, no {} in descriptions, every relationship label is double-quoted -->
~~~mermaid
erDiagram
    Owner ||--o{ Pet : "has"
    Pet ||--o{ Visit : "has"
    Pet }o--|| PetType : "is of"
    Vet }o--o{ Specialty : "has"
    Owner {
        int id PK
        string firstName
        string lastName
        string address
        string city
        string telephone
    }
    Pet {
        int id PK
        string name
        date birthDate
        int ownerId FK
        int typeId FK
    }
    PetType {
        int id PK
        string name
    }
    Visit {
        int id PK
        int petId FK
        date visitDate
        string description
    }
    Vet {
        int id PK
        string firstName
        string lastName
    }
    Specialty {
        int id PK
        string name
    }
~~~

### Step 4: Generate Key Repository Methods Section

For each service/module, document the key repository interfaces and produce the complete `## Key Repository Methods` section:

- Repository interface name, entity type, and source file path
- Standard CRUD methods inherited from base interface
- Custom query methods with their signatures and purposes — especially:
  - Bulk/batch queries (e.g., `findByPetIdIn(Collection<Integer>)`) used for cross-service aggregation
  - Custom finders with derived query methods
  - Named queries or `@Query`-annotated methods
  - Raw SQL or stored procedure calls
- Query method parameters and return types

### Step 5: Generate Caching Strategy Section

Identify caching layers and configuration and produce the complete `## Caching Strategy` section:

- Cache providers: EhCache, Redis, Caffeine, Spring Cache (`@Cacheable`, `@CacheEvict`), MemoryCache, IDistributedCache
- Cache configuration: TTL, eviction policies, cache regions/names
- Cache-aside, read-through, write-through, write-behind patterns
- Session caching, query result caching, second-level cache (Hibernate)
- Rationale for caching decisions (e.g., "veterinarian data is read frequently but changes rarely")
- JSR-107 (JCache) / `cache-api` usage and provider binding

### Step 6: Generate Data Ownership Boundaries Section

Document data-store topology and cross-service access semantics, plus data classification, then produce the complete `## Data Ownership Boundaries` section (including the `### Data Classification & Sensitivity` subsection):

**Boundaries:**
- Shared vs isolated data stores (shared database, database-per-service, logical separation within shared DB)
- Cross-service data access patterns: how one service queries another service's data (direct DB access vs REST API calls vs batch/bulk query methods such as `findByPetIdIn(...)` that enable gateway-level aggregation)
- Read/write patterns and CQRS observations across services

**Data Classification & Sensitivity (`### Data Classification & Sensitivity` subsection):**
- Identify whether stored data contains sensitive categories — PII (names, addresses, phone numbers, emails), PHI (health records), PCI (payment card data)
- For each sensitive category found, note whether encryption-at-rest, data masking, or field-level access controls are in place
- If absent, state this explicitly (e.g., "Owner entity stores PII (firstName, lastName, address, telephone); no encryption-at-rest or masking configured")

### Step 7: Save Output

Save to `.github/modernize/assessment/engines/facts/data-architecture.md` with this exact structure:

```
# Data Architecture & Persistence Layer

A brief introduction (1-2 sentences) summarizing the data layer.

## Database Configuration

[Table: Service/Module | DB Type | Profile | Driver | Connection | Migration Tool]

## Data Ownership per Service

[Table: Service | Tables Owned | ORM Framework | Caching | Notes]

## Entity Model

< Mermaid erDiagram here >

## Key Repository Methods

[Table: Service | Repository | Notable Methods | Purpose]

## Caching Strategy

[Table or description of caching layers, providers, TTL, patterns, and rationale]

## Data Ownership Boundaries

[Description of shared vs isolated data stores, cross-service data access patterns, and aggregation enablers]

### Data Classification & Sensitivity

[Table: Entity | Sensitive Fields | Classification (PII/PHI/PCI/None) | Controls in Place]
[If no sensitive data found: "No PII, PHI, or PCI data detected in entity model."]
```

## Scaling Rules

- If the project has **more than 30 entities**, aggregate minor entities and show only the core domain model (15-20 key entities)
- Keep the ER diagram under **40 entities** to ensure readability and GitHub rendering compatibility
- For multi-module projects, focus on inter-module entity relationships and data boundaries
- Collapse join tables into relationship annotations rather than showing them as separate entities
- In the repository methods table, focus on non-CRUD custom methods; omit standard inherited methods

## Common failure patterns observed in past runs

Each row below is something the model actually produced that crashed the diagram. Use the ✅ form.

| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed |
|---|---|---|
| `int OwnerId PK_FK` | `int OwnerId PK "FK to Owner"` | Compound key marker is not in grammar |
| `int OwnerId PK FK` | `int OwnerId PK "also FK to Owner"` | Two key markers on one line |
| `string Key PK "Redis key /basket/{BuyerId}"` | `string Key PK "Redis key /basket/<BuyerId>"` | `{` opens an entity block even inside quotes |
| `string Roles "comma-separated\nROLE_USER, ROLE_ADMIN"` | `string Roles "comma-separated; ROLE_USER, ROLE_ADMIN"` | Literal `\n` |
| `string user-name` | `string userName` | `-` not allowed in attribute name |
| `Owner ||--o{ Pet : has` | `Owner ||--o{ Pet : "has"` | Relationship label must be quoted |

## Error Handling

- **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.`
- **No data access layer found**: Output: `> ERROR: No recognized data access patterns or entities found at workspace-path. Verify the path is correct.`
- **Insufficient info**: Generate a best-effort diagram from available data. Add a note: `> Note: Some entities or relationships could not be fully identified.`

## Success Criteria

- Database configuration table lists all discovered databases with type, profile, driver, and migration tools
- Data ownership table maps each service to its owned tables, ORM, and caching layer
- Mermaid ER diagram renders correctly showing entity relationships with cardinality and key fields
- Repository methods table documents custom query methods with purposes, especially cross-service aggregation enablers
- Caching strategy section describes cache providers, patterns, and rationale
- Data ownership boundaries describe shared vs isolated stores and cross-service data access patterns
- Data Classification & Sensitivity table identifies PII/PHI/PCI fields and documents presence or absence of controls
- The ```mermaid block is preceded by the `<!-- mermaid-checked: ... -->` attestation comment
- File saved to `.github/modernize/assessment/engines/facts/data-architecture.md`