> ## Documentation Index
> Fetch the complete documentation index at: https://chameleon.voidlogger.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understand the design choices behind the framework: POJOs, flat stores, typed events, and memory-aware data handling.

## POJO-first entities

Chameleon stores cached data as plain objects. This reduces runtime overhead and avoids large class graphs sitting in memory.

That affects how you should think about the framework:

* entities are data, not rich active objects
* managers perform actions
* relations are often resolved lazily

## Flat store

Instead of nested caches like `guild.channels.cache`, Chameleon uses a flatter store model.

That keeps references simpler and reduces duplication pressure across cached structures.

## Typed events

Gateway events are exposed as discriminated unions. This gives you reliable narrowing based on `event.type`.

That is one of the strongest parts of the framework’s type story.

## REST results over exceptions

Many framework APIs return result objects:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const result = await client.messages.send(channelId, 'hello')

if (!result.ok) {
  console.error(result.error, result.status)
  return
}

console.log(result.data.id)
```

This keeps control flow explicit and predictable.

## Where the framework is still evolving

The broad architecture is coherent, but not every high-level API is equally polished yet. Builders and modal flows have improved a lot, while some lower-level surfaces still expose more raw structure than ideal.