# ARCHITECTURE.md

# Toolkit Architecture

```text
                           OpenAlex
                              │
                              ▼
              Query institutional research outputs
                              │
                              ▼
                     OpenAlex metadata
                              │
                              │
                              ▼
                  Repository snapshot
                    (kar_export.csv)
                              │
                              ▼
                    Comparison engine
         (DOI, title and metadata comparison)
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
   New publications     Existing records      Ambiguous
        (RIS)            (Enrichment)      (Manual review)
         │                    │                    │
         ▼                    ▼                    ▼
 Repository import      Update metadata      Staff review
```

---

## Outputs

The toolkit produces the following outputs:

* RIS files for new publications
* Metadata enrichment report
* Duplicate report
* Manual review report
* Raw OpenAlex JSON
* Log files

---

## Workflow summary

1. Export the institutional repository.
2. Query OpenAlex.
3. Compare OpenAlex metadata with the repository snapshot.
4. Classify each publication.
5. Generate reports and RIS files.
6. Repository staff review the outputs before import or metadata update.