# palemoky/chinese-poetry-api architecture

> Architecture diagram of the GitHub repository palemoky/chinese-poetry-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/palemoky/chinese-poetry-api
- Repository: https://github.com/palemoky/chinese-poetry-api

## Overview

This repository is a Chinese-poetry data importer and read-only API service. The main workflow is to load source JSON, normalize and classify poems, build simplified and traditional SQLite datasets, then serve filtered, searchable, paginated results through REST or GraphQL. The graph also preserves the documented author, dynasty, type, statistics, language-selection, and random-poem capabilities. Internal links are limited to relationships shown in excerpts or the source index; some route-to-handler details are documented at the router level, while unsampled implementation links are omitted.

Main entry points: [`internal/api/rest/router.go`](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/router.go) (REST routing), [`internal/database/repository_poems.go`](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/database/repository_poems.go) (Repository queries and writes), [`cmd/processor/main.go`](https://github.com/palemoky/chinese-poetry-api/blob/main/cmd/processor/main.go) (Import command), [`internal/processor/pipeline.go`](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/processor/pipeline.go) (Poem processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_processor_cli["Import command<br/>[main.go]"]
  node_json_loader["JSON loader<br/>[json_loader.go]"]
  node_processing["Poem processing<br/>[pipeline.go]"]
  node_finalization["Deduplication<br/>[finalize.go]"]
  node_classification["Classification and conversion"]
end

subgraph group_store["Persistence"]
  node_database[("SQLite database")]
  node_repository["Repository queries and writes"]
  node_migration["Schema migration<br/>[migrate.go]"]
end

subgraph group_rest["REST API"]
  node_server["HTTP server<br/>[main.go]"]
  node_configuration["Server configuration<br/>[config.go]"]
  node_rest_router["REST routing<br/>[router.go]"]
  node_middleware["Request middleware"]
  node_poem_api["Poem search and lists<br/>[poem.go]"]
  node_author_api["Author endpoints<br/>[author.go]"]
  node_dynasty_api["Dynasty endpoints<br/>[dynasty.go]"]
  node_type_api["Poetry type endpoints<br/>[poetry_type.go]"]
  node_health_stats["Health and statistics<br/>[health.go]"]
end

subgraph group_gql["GraphQL API"]
  node_graphql_server["GraphQL transport<br/>[server.go]"]
  node_graphql_resolvers["GraphQL resolvers"]
  node_resolver_context["Resolver dependencies<br/>[resolver.go]"]
end

node_clients(("API clients"))
node_poetry_corpus["Poetry JSON corpus"]

node_poetry_corpus -.->|"supplies data"| node_processor_cli
node_processor_cli -->|"loads JSON"| node_json_loader
node_processor_cli -->|"runs import"| node_processing
node_processor_cli -->|"opens and finalizes"| node_database
node_processing -->|"processes records"| node_json_loader
node_processing -->|"normalizes text"| node_classification
node_processing -->|"writes poem batches"| node_repository
node_processing -.->|"finalizes poems"| node_finalization
node_migration -->|"uses classifiers"| node_classification
node_processor_cli -.->|"prepares database"| node_migration
node_server -->|"loads settings"| node_configuration
node_server -->|"opens database"| node_database
node_server -->|"sets up routes"| node_rest_router
node_rest_router -->|"registers middleware"| node_middleware
node_rest_router -->|"routes poem requests"| node_poem_api
node_rest_router -->|"routes author requests"| node_author_api
node_rest_router -->|"routes dynasty requests"| node_dynasty_api
node_rest_router -->|"routes type requests"| node_type_api
node_rest_router -->|"routes health and stats"| node_health_stats
node_poem_api -->|"queries poems"| node_repository
node_author_api -->|"queries authors"| node_repository
node_dynasty_api -.->|"queries dynasties"| node_repository
node_type_api -.->|"queries types"| node_repository
node_health_stats -.->|"reads statistics"| node_repository
node_repository -->|"reads and writes"| node_database
node_clients -->|"requests REST"| node_rest_router
node_server -->|"registers GraphQL"| node_graphql_server
node_graphql_server -->|"dispatches queries"| node_graphql_resolvers
node_graphql_resolvers -->|"uses dependencies"| node_resolver_context
node_resolver_context -->|"queries data"| node_repository
node_clients -->|"requests GraphQL"| node_graphql_server

click node_processor_cli "https://github.com/palemoky/chinese-poetry-api/blob/main/cmd/processor/main.go"
click node_json_loader "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/loader/json_loader.go"
click node_processing "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/processor/pipeline.go"
click node_finalization "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/processor/finalize.go"
click node_classification "https://github.com/palemoky/chinese-poetry-api/tree/main/internal/classifier"
click node_database "https://github.com/palemoky/chinese-poetry-api/tree/main/internal/database"
click node_repository "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/database/repository_poems.go"
click node_migration "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/database/migrate.go"
click node_server "https://github.com/palemoky/chinese-poetry-api/blob/main/cmd/server/main.go"
click node_configuration "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/config/config.go"
click node_rest_router "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/router.go"
click node_middleware "https://github.com/palemoky/chinese-poetry-api/tree/main/internal/api/middleware"
click node_poem_api "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/poem.go"
click node_author_api "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/author.go"
click node_dynasty_api "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/dynasty.go"
click node_type_api "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/poetry_type.go"
click node_health_stats "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/health.go"
click node_graphql_server "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/server.go"
click node_graphql_resolvers "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/schema.resolvers.go"
click node_resolver_context "https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/resolver.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_processor_cli,node_json_loader,node_processing,node_finalization,node_classification,node_clients toneBlue
class node_database,node_repository,node_migration toneAmber
class node_server,node_configuration,node_rest_router,node_middleware,node_poem_api,node_author_api,node_dynasty_api,node_type_api,node_health_stats toneMint
class node_graphql_server,node_graphql_resolvers,node_resolver_context toneRose
class node_poetry_corpus toneIndigo
```

## Components

### Data ingestion

- [Import command](https://github.com/palemoky/chinese-poetry-api/blob/main/cmd/processor/main.go): `cmd/processor/main.go`
- [JSON loader](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/loader/json_loader.go): `internal/loader/json_loader.go`
- [Poem processing](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/processor/pipeline.go): `internal/processor/pipeline.go`
- [Deduplication](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/processor/finalize.go): `internal/processor/finalize.go`
- [Classification and conversion](https://github.com/palemoky/chinese-poetry-api/tree/main/internal/classifier): `internal/classifier`

### Persistence

- [SQLite database](https://github.com/palemoky/chinese-poetry-api/tree/main/internal/database): `internal/database`
- [Repository queries and writes](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/database/repository_poems.go): `internal/database/repository_poems.go`
- [Schema migration](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/database/migrate.go): `internal/database/migrate.go`

### REST API

- [HTTP server](https://github.com/palemoky/chinese-poetry-api/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Server configuration](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/config/config.go): `internal/config/config.go`
- [REST routing](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/router.go): `internal/api/rest/router.go`
- [Request middleware](https://github.com/palemoky/chinese-poetry-api/tree/main/internal/api/middleware): `internal/api/middleware`
- [Poem search and lists](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/poem.go): `internal/api/rest/handler/poem.go`
- [Author endpoints](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/author.go): `internal/api/rest/handler/author.go`
- [Dynasty endpoints](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/dynasty.go): `internal/api/rest/handler/dynasty.go`
- [Poetry type endpoints](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/poetry_type.go): `internal/api/rest/handler/poetry_type.go`
- [Health and statistics](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/api/rest/handler/health.go): `internal/api/rest/handler/health.go`

### GraphQL API

- [GraphQL transport](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/server.go): `internal/graph/server.go`
- [GraphQL resolvers](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/schema.resolvers.go): `internal/graph/schema.resolvers.go`
- [Resolver dependencies](https://github.com/palemoky/chinese-poetry-api/blob/main/internal/graph/resolver.go): `internal/graph/resolver.go`

### Other components

- **API clients**
- **Poetry JSON corpus**

## Connections

- Poetry JSON corpus → Import command: supplies data
- Import command → JSON loader: loads JSON (evidence: `cmd/processor/main.go`)
- Import command → Poem processing: runs import (evidence: `cmd/processor/main.go`)
- Import command → SQLite database: opens and finalizes (evidence: `cmd/processor/main.go`)
- Poem processing → JSON loader: processes records (evidence: `internal/processor/pipeline.go`)
- Poem processing → Classification and conversion: normalizes text (evidence: `internal/processor/pipeline.go`)
- Poem processing → Repository queries and writes: writes poem batches (evidence: `internal/processor/pipeline.go`)
- Poem processing → Deduplication: finalizes poems
- Schema migration → Classification and conversion: uses classifiers (evidence: `internal/database/migrate.go`)
- Import command → Schema migration: prepares database
- HTTP server → Server configuration: loads settings (evidence: `cmd/server/main.go`)
- HTTP server → SQLite database: opens database (evidence: `cmd/server/main.go`)
- HTTP server → REST routing: sets up routes (evidence: `cmd/server/main.go`)
- REST routing → Request middleware: registers middleware (evidence: `internal/api/rest/router.go`)
- REST routing → Poem search and lists: routes poem requests (evidence: `internal/api/rest/router.go`)
- REST routing → Author endpoints: routes author requests (evidence: `internal/api/rest/router.go`)
- REST routing → Dynasty endpoints: routes dynasty requests (evidence: `internal/api/rest/router.go`)
- REST routing → Poetry type endpoints: routes type requests (evidence: `internal/api/rest/router.go`)
- REST routing → Health and statistics: routes health and stats (evidence: `internal/api/rest/router.go`)
- Poem search and lists → Repository queries and writes: queries poems (evidence: `internal/api/rest/handler/poem.go`)
- Author endpoints → Repository queries and writes: queries authors (evidence: `internal/api/rest/handler/author.go`)
- Dynasty endpoints → Repository queries and writes: queries dynasties
- Poetry type endpoints → Repository queries and writes: queries types
- Health and statistics → Repository queries and writes: reads statistics
- Repository queries and writes → SQLite database: reads and writes (evidence: `internal/database/repository_write.go`)
- API clients → REST routing: requests REST (evidence: `README.md`)
- HTTP server → GraphQL transport: registers GraphQL (evidence: `cmd/server/main.go`)
- GraphQL transport → GraphQL resolvers: dispatches queries (evidence: `internal/graph/server.go`)
- GraphQL resolvers → Resolver dependencies: uses dependencies (evidence: `internal/graph/schema.resolvers.go`)
- Resolver dependencies → Repository queries and writes: queries data (evidence: `internal/graph/resolver.go`)
- API clients → GraphQL transport: requests GraphQL (evidence: `README.md`)
