# masaudahmod/your-toast architecture

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

- Interactive diagram: https://gitdiagram.com/masaudahmod/your-toast
- Repository: https://github.com/masaudahmod/your-toast

## Overview

1. **Project type and boundary**
   - This is a **client-side React toast notification library**, not an application. Its architecture is centered around exposing a small public API that drives an internal toast state store and a rendering provider.

2. **Public entrypoint**
   - `src/index.ts` is the package surface. It likely re-exports the provider, toast API, hook, and shared types so consumers can import from `your-toast` directly.
   - The published package is built into `dist/index.js`, indicating a compiled library distribution rather than a runtime app.

3. **Core command API**
   - `src/core/toast.ts` appears to implement the imperative API used by consumers: `toast()`, variant helpers like `toast.success/error/loading`, `toast.promise`, plus control methods such as `update` and `dismiss`.
   - This layer is the main orchestration point between user calls and the internal store.

4. **Variant model**
   - `src/core/variants.ts` likely defines the supported toast kinds: `default`, `success`, `error`, `loading`, and `action`.
   - Variants are a key architectural boundary because they determine both behavior and presentation.

5. **Shared state store**
   - `src/store/toastStore.ts` is the central state container. It likely holds the active toast list, stack/limit behavior, and subscriber notifications.
   - This store is what makes the library controllable from outside React component trees and supports updates/dismissals by id.

6. **Provider and rendering layer**
   - `src/components/YourToastProvider.tsx` is the UI boundary that connects the store to React rendering.
   - Consumers wrap their app with this provider so toast state changes can be observed and rendered as visible notifications.

7. **Hook-based access**
   - `src/hooks/useToast.ts` is the React-friendly access point for components that want to trigger toasts without using the global imperative import directly.
   - This separates “triggering” from “rendering,” while still using the same underlying store.

8. **Type contracts**
   - `src/types/toast.ts` defines the data model for toast objects and options.
   - These types are the contract between the public API, store, and UI components, ensuring the same shape is used throughout the system.

9. **Main data flow**
   - A consumer calls `toast(...)` or `toast.promise(...)`.
   - The core API creates or updates a toast record in the store.
   - `YourToastProvider` subscribes to store changes and renders the active toast stack.
   - User actions or timers then call back into the store for dismiss/update behavior.

10. **Build and packaging**
   - `tsconfig.json` and `tsup.config.ts` show a TypeScript library build pipeline.
   - `tsup` is the packaging tool, which is typical for a reusable NPM package because it emits distributable JS from the `src/` tree into `dist/`.

11. **Architectural shape**
   - The repo is organized into a clean separation of **API orchestration** (`core`), **state management** (`store`), **presentation** (`components`), **React integration** (`hooks`), and **shared contracts** (`types`).
   - That separation is the main thing to capture in an architecture diagram: user-facing calls go into core/store, and the provider is the rendering endpoint.

Main entry points: [`src/index.ts`](https://github.com/masaudahmod/your-toast/blob/main/src/index.ts) (index), [`src/core/toast.ts`](https://github.com/masaudahmod/your-toast/blob/main/src/core/toast.ts) (toast API), [`src/store/toastStore.ts`](https://github.com/masaudahmod/your-toast/blob/main/src/store/toastStore.ts) (toast store), [`src/components/YourToastProvider.tsx`](https://github.com/masaudahmod/your-toast/blob/main/src/components/YourToastProvider.tsx) (ToastProvider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["Public API"]
  node_node_index["index<br/>entrypoint<br/>[index.ts]"]
  node_node_types["toast types<br/>contracts<br/>[toast.ts]"]
end

subgraph group_group_runtime["Toast Runtime"]
  node_node_toast_api["toast API<br/>commands<br/>[toast.ts]"]
  node_node_variants["variants<br/>model<br/>[variants.ts]"]
  node_node_store[("toast store<br/>state store<br/>[toastStore.ts]")]
end

subgraph group_group_ui["React UI"]
  node_node_provider["ToastProvider<br/>react provider"]
  node_node_hook["useToast<br/>react hook<br/>[useToast.ts]"]
end

subgraph group_group_build["Build & Dist"]
  node_node_dist["dist build<br/>compiled output<br/>[index.js]"]
  node_node_tsup["tsup config<br/>build config<br/>[tsup.config.ts]"]
  node_node_tsconfig["tsconfig<br/>typescript config<br/>[tsconfig.json]"]
end

node_node_index -->|"re-exports"| node_node_toast_api
node_node_index -->|"re-exports"| node_node_provider
node_node_index -->|"re-exports"| node_node_hook
node_node_index -->|"re-exports"| node_node_types
node_node_toast_api -->|"writes"| node_node_store
node_node_toast_api -->|"uses"| node_node_variants
node_node_toast_api -->|"depends on"| node_node_types
node_node_store -->|"stores"| node_node_types
node_node_provider -->|"subscribes"| node_node_store
node_node_provider -->|"renders"| node_node_variants
node_node_hook -->|"calls"| node_node_toast_api
node_node_hook -.->|"reads"| node_node_store
node_node_dist -->|"built from"| node_node_index
node_node_tsup -->|"produces"| node_node_dist
node_node_tsconfig -.->|"supports"| node_node_tsup

click node_node_index "https://github.com/masaudahmod/your-toast/blob/main/src/index.ts"
click node_node_toast_api "https://github.com/masaudahmod/your-toast/blob/main/src/core/toast.ts"
click node_node_variants "https://github.com/masaudahmod/your-toast/blob/main/src/core/variants.ts"
click node_node_store "https://github.com/masaudahmod/your-toast/blob/main/src/store/toastStore.ts"
click node_node_types "https://github.com/masaudahmod/your-toast/blob/main/src/types/toast.ts"
click node_node_provider "https://github.com/masaudahmod/your-toast/blob/main/src/components/YourToastProvider.tsx"
click node_node_hook "https://github.com/masaudahmod/your-toast/blob/main/src/hooks/useToast.ts"
click node_node_dist "https://github.com/masaudahmod/your-toast/blob/main/dist/index.js"
click node_node_tsup "https://github.com/masaudahmod/your-toast/blob/main/tsup.config.ts"
click node_node_tsconfig "https://github.com/masaudahmod/your-toast/blob/main/tsconfig.json"

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_node_index,node_node_types toneBlue
class node_node_toast_api,node_node_variants,node_node_store toneAmber
class node_node_provider,node_node_hook toneMint
class node_node_dist,node_node_tsup,node_node_tsconfig toneRose
```

## Components

### Public API

Package surface exported to consumers.

- [index](https://github.com/masaudahmod/your-toast/blob/main/src/index.ts): entrypoint · Package entry that re-exports the public surface. · `src/index.ts`
- [toast types](https://github.com/masaudahmod/your-toast/blob/main/src/types/toast.ts): contracts · Shared toast and option data shapes used across the package. · `src/types/toast.ts`

### Toast Runtime

Imperative API and shared state that manage toast lifecycle.

- [toast API](https://github.com/masaudahmod/your-toast/blob/main/src/core/toast.ts): commands · Imperative toast creation, update, dismiss, and promise helpers. · `src/core/toast.ts`
- [variants](https://github.com/masaudahmod/your-toast/blob/main/src/core/variants.ts): model · Supported toast kinds and variant behavior. · `src/core/variants.ts`
- [toast store](https://github.com/masaudahmod/your-toast/blob/main/src/store/toastStore.ts): state store · Central toast state, subscriptions, and lifecycle coordination. · `src/store/toastStore.ts`

### React UI

Provider and hook that connect state to rendering and component use.

- [ToastProvider](https://github.com/masaudahmod/your-toast/blob/main/src/components/YourToastProvider.tsx): react provider · Subscribes to toast store and renders active notifications. · `src/components/YourToastProvider.tsx`
- [useToast](https://github.com/masaudahmod/your-toast/blob/main/src/hooks/useToast.ts): react hook · Hook-based access to the toast API for components. · `src/hooks/useToast.ts`

### Build & Dist

TypeScript library build and published output.

- [dist build](https://github.com/masaudahmod/your-toast/blob/main/dist/index.js): compiled output · Published bundled JavaScript output. · `dist/index.js`
- [tsup config](https://github.com/masaudahmod/your-toast/blob/main/tsup.config.ts): build config · Library bundling and packaging configuration. · `tsup.config.ts`
- [tsconfig](https://github.com/masaudahmod/your-toast/blob/main/tsconfig.json): typescript config · TypeScript compilation settings for the library build. · `tsconfig.json`

## Connections

- index → toast API: re-exports · Package consumers import the command API from the entrypoint.
- index → ToastProvider: re-exports · Entry point exposes the provider component.
- index → useToast: re-exports · Entry point exposes the hook API.
- index → toast types: re-exports · Entry point exposes shared types.
- toast API → toast store: writes · Commands create, update, dismiss, and resolve toast records through the store.
- toast API → variants: uses · Variant helpers and special-case behavior are defined by supported toast kinds.
- toast API → toast types: depends on · Public API shapes are typed by shared contracts.
- toast store → toast types: stores · Store state is composed of the toast data model.
- ToastProvider → toast store: subscribes · Provider observes store changes to render active toasts.
- ToastProvider → variants: renders · Presentation varies by toast kind.
- useToast → toast API: calls · Hook provides ergonomic access to the imperative API.
- useToast → toast store: reads · Hook may coordinate with the shared store for toast state.
- dist build → index: built from · Distribution output is compiled from the source entrypoint.
- tsup config → dist build: produces · Bundler configuration emits the distributable build.
- tsconfig → tsup config: supports · TypeScript settings support the build pipeline.
