# razanfawwaz/sirekap-api architecture

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

- Interactive diagram: https://gitdiagram.com/razanfawwaz/sirekap-api
- Repository: https://github.com/razanfawwaz/sirekap-api

## Overview

#### Purpose and principal workflow
This Go API exposes read-only election vote counts by polling station. An HTTP client initiates the main workflow with `GET /api/v1/ppwp?limit=…&offset=…`; Gin routes the request to a handler that parses pagination, requests records from PostgreSQL, and returns JSON in a standard response envelope. The README describes the records as data collected from the official KPU election site, but the sampled code shows database reads, not collection or ingestion.

#### Components

##### HTTP application and response
- **Gin server and route registration** — `main.go`: configures Gin, registers `/ping` and `/api/v1/ppwp`, connects the database, and starts the server on the configured port.
- **PPWP HTTP handler** — `interfaces/ppwp_handler.go`: reads `limit` and `offset`, validates that `limit` is present, calls the application operation, and serializes success or error responses.
- **Response envelope and pagination type** — `config/base_response.go`: defines the JSON response shape used by the handler, plus a page metadata type.

##### Election-data query and representation
- **PPWP application operation** — `application/ppwp.go`: obtains the configured database handle, constructs the repository, and delegates the paginated data request.
- **PPWP PostgreSQL repository** — `repository/ppwp_repository.go`: selects polling-station election fields from `ppwp_tps`, filters to rows with `status_suara` true, applies SQL limit and offset, and scans results into domain records.
- **Election report domain models** — `domain/ppwp.go`: defines the flat and nested structures for regional identifiers, candidate votes, voter counts, tally-image references, and status fields.

##### Runtime configuration and external systems
- **Database and environment configuration** — `config/config.go`: reads settings through Viper, opens a PostgreSQL `database/sql` connection, and exposes the database handle.
- **HTTP client** — `null`: External caller that sends the PPWP request; no repository path.
- **PostgreSQL database** — `null`: External state system queried by the repository; the configured database contains the `ppwp_tps` table.
- **KPU election-data source** — `null`: The README identifies the official KPU site as the upstream source for collected data, but no ingestion path is established by the sampled code.

#### Relationships
- HTTP client -> Gin server and route registration: sends the documented PPWP request; evidence: `README.md`.
- Gin server and route registration -> PPWP HTTP handler: registers the handler for `GET /api/v1/ppwp`; evidence: `main.go`.
- Gin server and route registration -> Database and environment configuration: connects the database before starting the server; evidence: `main.go`.
- PPWP HTTP handler -> PPWP application operation: passes parsed limit and offset to `GetAllData`; evidence: `interfaces/ppwp_handler.go`.
- PPWP HTTP handler -> Response envelope and pagination type: constructs the response envelope for validation, error, and success outcomes; evidence: `interfaces/ppwp_handler.go`.
- PPWP application operation -> Database and environment configuration: obtains the database handle with `GetDB`; evidence: `application/ppwp.go`.
- PPWP application operation -> PPWP PostgreSQL repository: constructs the repository and calls `GetAllData`; evidence: `application/ppwp.go`.
- PPWP PostgreSQL repository -> Election report domain models: scans query results into `domain.ReportData`; evidence: `repository/ppwp_repository.go`.
- PPWP PostgreSQL repository -> PostgreSQL database: queries `ppwp_tps` with a status filter and pagination; evidence: `repository/ppwp_repository.go`.
- PPWP HTTP handler -> HTTP client: returns the query result as JSON; evidence: `interfaces/ppwp_handler.go`.
- KPU election-data source -> PostgreSQL database: upstream collection is documented, but implementation and wiring are not shown; evidence: none (inferred).

#### Coverage limits
The sampled files establish the API’s read path and PostgreSQL query, but not how election data reaches the database, database schema, deployment topology, or behavior for malformed numeric pagination values. The source index identifies no additional substantial application modules beyond those represented here.

Main entry points: [`interfaces/ppwp_handler.go`](https://github.com/razanfawwaz/sirekap-api/blob/main/interfaces/ppwp_handler.go) (PPWP handler), [`main.go`](https://github.com/razanfawwaz/sirekap-api/blob/main/main.go) (Gin server and routes), [`application/ppwp.go`](https://github.com/razanfawwaz/sirekap-api/blob/main/application/ppwp.go) (PPWP operation), [`repository/ppwp_repository.go`](https://github.com/razanfawwaz/sirekap-api/blob/main/repository/ppwp_repository.go) (PPWP repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http_api["HTTP API"]
  node_gin_server["Gin server and routes<br/>HTTP server"]
  node_ppwp_handler["PPWP handler<br/>HTTP handler"]
  node_response_envelope["Response envelope<br/>JSON response"]
end

subgraph group_ppwp_read["PPWP Read Path"]
  node_ppwp_operation["PPWP operation<br/>Application operation"]
  node_ppwp_repository["PPWP repository<br/>PostgreSQL repository"]
  node_election_models["Election report models<br/>Domain models"]
end

subgraph group_runtime_data["Runtime Configuration"]
  node_db_config["Database configuration<br/>[config.go]"]
end

node_http_client(("HTTP client<br/>External caller"))
node_postgres[("PostgreSQL<br/>Database")]
node_kpu_source["KPU election-data source<br/>External data source"]

node_http_client -->|"sends request"| node_gin_server
node_gin_server -->|"routes request"| node_ppwp_handler
node_gin_server -->|"connects database"| node_db_config
node_ppwp_handler -->|"passes pagination"| node_ppwp_operation
node_ppwp_handler -->|"builds response"| node_response_envelope
node_ppwp_operation -->|"gets database handle"| node_db_config
node_ppwp_operation -->|"calls query"| node_ppwp_repository
node_ppwp_repository -->|"scans results"| node_election_models
node_ppwp_repository -->|"queries records"| node_postgres
node_ppwp_handler -->|"returns JSON"| node_http_client
node_kpu_source -.->|"supplies data"| node_postgres

click node_gin_server "https://github.com/razanfawwaz/sirekap-api/blob/main/main.go"
click node_ppwp_handler "https://github.com/razanfawwaz/sirekap-api/blob/main/interfaces/ppwp_handler.go"
click node_response_envelope "https://github.com/razanfawwaz/sirekap-api/blob/main/config/base_response.go"
click node_ppwp_operation "https://github.com/razanfawwaz/sirekap-api/blob/main/application/ppwp.go"
click node_ppwp_repository "https://github.com/razanfawwaz/sirekap-api/blob/main/repository/ppwp_repository.go"
click node_election_models "https://github.com/razanfawwaz/sirekap-api/blob/main/domain/ppwp.go"
click node_db_config "https://github.com/razanfawwaz/sirekap-api/blob/main/config/config.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_gin_server,node_ppwp_handler,node_response_envelope,node_http_client toneBlue
class node_ppwp_operation,node_ppwp_repository,node_election_models,node_postgres toneAmber
class node_db_config toneMint
class node_kpu_source toneIndigo
```

## Components

### HTTP API

- [Gin server and routes](https://github.com/razanfawwaz/sirekap-api/blob/main/main.go): HTTP server · `main.go`
- [PPWP handler](https://github.com/razanfawwaz/sirekap-api/blob/main/interfaces/ppwp_handler.go): HTTP handler · `interfaces/ppwp_handler.go`
- [Response envelope](https://github.com/razanfawwaz/sirekap-api/blob/main/config/base_response.go): JSON response · `config/base_response.go`

### PPWP Read Path

- [PPWP operation](https://github.com/razanfawwaz/sirekap-api/blob/main/application/ppwp.go): Application operation · `application/ppwp.go`
- [PPWP repository](https://github.com/razanfawwaz/sirekap-api/blob/main/repository/ppwp_repository.go): PostgreSQL repository · `repository/ppwp_repository.go`
- [Election report models](https://github.com/razanfawwaz/sirekap-api/blob/main/domain/ppwp.go): Domain models · `domain/ppwp.go`

### Runtime Configuration

- [Database configuration](https://github.com/razanfawwaz/sirekap-api/blob/main/config/config.go): Database configuration · `config/config.go`

### Other components

- **HTTP client**: External caller
- **PostgreSQL**: Database · Configured database containing the ppwp_tps table.
- **KPU election-data source**: External data source · Upstream source identified by the README; ingestion is not shown in sampled code.

## Connections

- HTTP client → Gin server and routes: sends request (evidence: `README.md`)
- Gin server and routes → PPWP handler: routes request (evidence: `main.go`)
- Gin server and routes → Database configuration: connects database (evidence: `main.go`)
- PPWP handler → PPWP operation: passes pagination (evidence: `interfaces/ppwp_handler.go`)
- PPWP handler → Response envelope: builds response (evidence: `interfaces/ppwp_handler.go`)
- PPWP operation → Database configuration: gets database handle (evidence: `application/ppwp.go`)
- PPWP operation → PPWP repository: calls query (evidence: `application/ppwp.go`)
- PPWP repository → Election report models: scans results (evidence: `repository/ppwp_repository.go`)
- PPWP repository → PostgreSQL: queries records (evidence: `repository/ppwp_repository.go`)
- PPWP handler → HTTP client: returns JSON (evidence: `interfaces/ppwp_handler.go`)
- KPU election-data source → PostgreSQL: supplies data · Inferred; not shown in the code that was read.
