# smithsonian/dpo-packrat architecture

> Architecture diagram of the GitHub repository smithsonian/dpo-packrat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smithsonian/dpo-packrat
- Repository: https://github.com/smithsonian/dpo-packrat

## Overview

##### Project Type and Purpose
- This is a monorepo for a full-stack application called **dpo-packrat**, which manages 3D data captures, models, and scenes.
- It comprises:
- A React-based SPA in `client/`
- A Node.js-TypeScript GraphQL API + HTTP server in `server/`
- A shared TypeScript library in `common/`
- Docker and Nginx configuration in `conf/`
- End-to-end and unit tests in `e2e/` and `server/tests/`
- Documentation site in `docs/`

##### High-Level File-Structure Analysis
- Top-level packages managed by Lerna:
- `client/` – React app, components, pages, GraphQL client, Redux store
- `common/` – Shared types/constants/utilities
- `server/` – GraphQL schemas, Prisma models, many service modules (auth, cache, event, storage, job, workflow, navigation, metadata, audit, collections), HTTP routes, utilities
- Configuration for Docker Compose (`conf/docker/*`), Nginx (`conf/nginx/*`), and deployment scripts (`conf/scripts/*`)
- Test directories separate concerns: e2e tests target the client/server, server side unit tests cover each domain module and GraphQL layer

##### Key README Insights
- The system runs in Docker containers: client, server, DB, Solr, Nginx proxy.
- Uses Prisma for DB access (PostgreSQL or similar), Solr for enterprise search, Passport for LDAP/Local auth.
- GraphQL code generation required when schema changes.
- Two modes: Docker-based (dev/prod) and local dev without Docker (manually start client, server, common).

##### Main Components & Interactions
a.  Frontend (React SPA)
- Hosted in Docker or on port 3000
- Uses Apollo Client (or GraphQL fetch) to call server’s GraphQL endpoint
- Auth flow integrates via HTTP cookie / token from server
b.  Backend (Node.js / TypeScript)
- **HTTP Layer**: Express (or built-in HTTP) with routes for GraphQL, WebDAV, downloads, sitemap, health checks
- **GraphQL Engine**: Apollo Server or equivalent, with schema defined under `server/graphql/schema` and resolvers under `server/graphql/api`
- **Auth Module**: Passport strategies (LDAP, Local) under `server/auth`
- **Database Layer**: Prisma client generated from `server/db/prisma/schema.prisma`; custom ORM wrappers in `server/db/api`
- **Event Bus**: In-process event engine for pub/sub across modules
- **Cache**: In-memory or Redis-like abstraction for licenses, users, vocabulary, system objects
- **Storage**: OCFL-compliant local file storage with adapters under `server/storage`
- **Metadata Extraction**: Image/video metadata via ExifTool/Exifr under `server/metadata`
- **Job & Workflow Engines**: Long-running tasks (Cook, NS, Packrat) under `server/job` and `server/workflow`
- **Navigation / Search**: Indexing and querying Solr cores under `server/navigation` and `server/config/solr`
- **Audit & Reporting**: Audit events, generators, reporting under `server/audit` and `server/report`
c.  External Services
- **Database**: PostgreSQL (or MySQL) container via Docker Compose
- **Solr**: Standalone Solr containers with multiple cores (packrat, packratMeta)
- **Nginx Proxy**: SSL termination, routing to client and server containers
- **LDAP server** (optional) for authentication

##### Architectural Patterns & Principles
- **Modularization**: Each domain (auth, cache, storage, event, job, workflow, metadata, navigation) follows an interface/impl/factory structure
- **Factory Pattern** for creating adapters (AuthFactory, StorageFactory, EventFactory, CollectionFactory, ReportFactory, etc.)
- **In-Process Event Bus** to decouple subsystems
- **GraphQL Schema-First** approach + codegen + Prisma ORM
- **Containerization** via Docker Compose for full-stack isolation and reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    Browser["User’s Browser"]:::frontend
    Client["React SPA<br/>(client/)"]:::frontend
    click Client "https://github.com/smithsonian/dpo-packrat/tree/master/client/"

    %% API Gateway / Proxy
    Nginx["Nginx Proxy<br/>(conf/nginx/)"]:::infra
    click Nginx "https://github.com/smithsonian/dpo-packrat/tree/master/conf/nginx/"

    %% Server Container
    subgraph "GraphQL & HTTP Server" 
        direction TB
        HTTP["HTTP Layer<br/>(server/http/)"]:::backend
        click HTTP "https://github.com/smithsonian/dpo-packrat/tree/master/server/http/"
        GraphQL["GraphQL Engine<br/>(server/graphql/)"]:::backend
        click GraphQL "https://github.com/smithsonian/dpo-packrat/tree/master/server/graphql/"
        Auth["Authentication Module<br/>(server/auth/)"]:::backend
        click Auth "https://github.com/smithsonian/dpo-packrat/tree/master/server/auth/"
        DBLayer["Database Layer<br/>(server/db/)"]:::backend
        click DBLayer "https://github.com/smithsonian/dpo-packrat/tree/master/server/db/"
        EventBus["Event Bus<br/>(server/event/)"]:::backend
        click EventBus "https://github.com/smithsonian/dpo-packrat/tree/master/server/event/"
        Cache["Cache Abstraction<br/>(server/cache/)"]:::backend
        click Cache "https://github.com/smithsonian/dpo-packrat/tree/master/server/cache/"
        Storage["Storage Layer<br/>(server/storage/)"]:::backend
        click Storage "https://github.com/smithsonian/dpo-packrat/tree/master/server/storage/"
        Metadata["Metadata Extraction<br/>(server/metadata/)"]:::backend
        click Metadata "https://github.com/smithsonian/dpo-packrat/tree/master/server/metadata/"
        Job["Job Engine<br/>(server/job/)"]:::backend
        click Job "https://github.com/smithsonian/dpo-packrat/tree/master/server/job/"
        Workflow["Workflow Engine<br/>(server/workflow/)"]:::backend
        click Workflow "https://github.com/smithsonian/dpo-packrat/tree/master/server/workflow/"
        Navigation["Navigation/Search<br/>(server/navigation/)"]:::backend
        click Navigation "https://github.com/smithsonian/dpo-packrat/tree/master/server/navigation/"
        Audit["Audit & Reporting<br/>(server/audit/, server/report/)"]:::backend
        click Audit "https://github.com/smithsonian/dpo-packrat/tree/master/server/audit/"
        click Audit "https://github.com/smithsonian/dpo-packrat/tree/master/server/report/"
        Records["Logging & Notifications<br/>(server/records/)"]:::backend
        click Records "https://github.com/smithsonian/dpo-packrat/tree/master/server/records/"
        Utils["Utility Functions & Parsers<br/>(server/utils/)"]:::backend
        click Utils "https://github.com/smithsonian/dpo-packrat/tree/master/server/utils/"
        Types["Type Definitions<br/>(server/types/)"]:::backend
        click Types "https://github.com/smithsonian/dpo-packrat/tree/master/server/types/"
    end

    %% Shared Library
    Common["Shared Library<br/>(common/)"]:::frontend
    click Common "https://github.com/smithsonian/dpo-packrat/tree/master/common/"

    %% Docker & Deployment Configs
    subgraph "Configuration" 
        DockerConf["Docker Config<br/>(conf/docker/)"]:::infra
        click DockerConf "https://github.com/smithsonian/dpo-packrat/tree/master/conf/docker/"
        Scripts["Deployment Scripts<br/>(conf/scripts/)"]:::infra
        click Scripts "https://github.com/smithsonian/dpo-packrat/tree/master/conf/scripts/"
        Docs["Documentation Site<br/>(docs/)"]:::infra
        click Docs "https://github.com/smithsonian/dpo-packrat/tree/master/docs/"
    end

    %% Tests
    E2E["End-to-End Tests<br/>(e2e/)"]:::infra
    click E2E "https://github.com/smithsonian/dpo-packrat/tree/master/e2e/"
    UnitTests["Server Unit Tests<br/>(server/tests/)"]:::infra
    click UnitTests "https://github.com/smithsonian/dpo-packrat/tree/master/server/tests/"

    %% Infrastructure Services
    DB["PostgreSQL DB"]:::datastore
    Solr["Solr Search"]:::datastore
    LDAP["LDAP Server (optional)"]:::infra
    FS["Storage Volume<br/>(OCFL Data)"]:::datastore

    %% Connections
    Browser -->|loads SPA| Client
    Client -->|HTTP/GraphQL| Nginx
    Nginx -->|forwards GraphQL| HTTP
    Nginx -->|serves static| Client
    HTTP -->|executes| GraphQL
    HTTP -->|auth calls| Auth
    Auth -->|verifies| LDAP
    GraphQL -->|queries| DBLayer
    GraphQL -->|pub/sub| EventBus
    EventBus -.->|triggers| Job
    EventBus -.->|triggers| Workflow
    Job -->|reads/writes| DBLayer
    Workflow -->|reads/writes| DBLayer
    DBLayer -->|connects| DB
    GraphQL -->|cache get/set| Cache
    GraphQL -->|storage ops| Storage
    Storage -->|writes/reads| FS
    Metadata -->|extracts| Storage
    GraphQL -->|metadata| Metadata
    Navigation -->|index/query| Solr
    GraphQL -->|search ops| Navigation
    Audit -->|logs events| DBLayer
    Records -->|notifications| HTTP
    Utils -->|utils| HTTP
    Types -->|types| GraphQL

    %% Shared/Common
    HTTP -->|imports types| Common
    GraphQL -->|imports utils| Common

    %% Tests/Docs/Config
    E2E --> Client
    E2E --> HTTP
    UnitTests --> HTTP
    UnitTests --> GraphQL
    Docs --> Common

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32
    classDef backend fill:#e3f2fd,stroke:#1565c0,color:#1565c0
    classDef infra fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef datastore fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
```
