> For the complete documentation index, see [llms.txt](https://gokiburi.gitbook.io/gokiburi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gokiburi.gitbook.io/gokiburi-docs/onchain-architecture.md).

# On-chain Architecture

GOKIBURI separates ownership, genome selection, narrative logic, and SVG rendering into focused contracts and libraries.

## Token flow

1. A token ID is minted by the ERC-721 collection contract.
2. `RoachGenome.traitsOf(tokenId)` derives deterministic traits.
3. The collection routes named 1/1 IDs to the Rare renderer and all other IDs to the Common renderer.
4. The selected renderer returns an SVG string.
5. `RoachLore` derives Hidden Title, Threat Level, and Observation Log values.
6. The collection builds JSON metadata and returns it as a Base64 data URI.

## Main components

| Component       | Responsibility                                             |
| --------------- | ---------------------------------------------------------- |
| `GOKIBURI`      | ERC-721 ownership, minting, routing, and metadata assembly |
| `RoachGenome`   | Deterministic trait generation                             |
| `RoachLore`     | Deterministic narrative metadata                           |
| Common renderer | SVG for non-1/1 specimens                                  |
| Rare renderer   | SVG for named 1/1 specimens                                |

## Data URI structure

`tokenURI` returns:

```
data:application/json;base64,<BASE64_JSON>
```

The decoded JSON contains an SVG image URI:

```
data:image/svg+xml;base64,<BASE64_SVG>
```

This keeps the artwork and metadata directly accessible through the contract interface.

## Renderer finalization

The owner can update the Common and Rare renderer addresses during the Beta design phase. Calling `freezeRenderers()` permanently disables future renderer updates in the collection contract.

The on-chain `renderersFrozen` value is the authoritative indicator of whether the visual implementation has been finalized.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gokiburi.gitbook.io/gokiburi-docs/onchain-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.