# itsflaid/katalyst architecture

> Architecture diagram of the GitHub repository itsflaid/katalyst, 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/itsflaid/katalyst
- Repository: https://github.com/itsflaid/katalyst

## Overview

Katalyst is a decision-support app for small businesses: staff record sales and owners review performance, manage products and inventory, and test pricing scenarios. Its documented workflow runs from transaction entry through stored receipt data to dashboard and period analytics; the simulator and grounded Copilot are separate decision-support branches. The graph combines documented capabilities with sampled analytics/query references. Several route-to-domain and Copilot-tool call paths were not shown, so those relationships are omitted rather than inferred.

Main entry points: [`src/lib/server/domains/facts/queries.ts`](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/facts/queries.ts) (Fact Queries), [`src/routes/copilot/chat/+server.ts`](https://github.com/itsflaid/katalyst/blob/main/src/routes/copilot/chat/%2Bserver.ts) (Copilot Chat), [`src/routes/transactions/+page.server.ts`](https://github.com/itsflaid/katalyst/blob/main/src/routes/transactions/%2Bpage.server.ts) (Sales and Product UI), [`src/lib/server/domains/stats/loaders.ts`](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/stats/loaders.ts) (Statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sales["Sales and Catalog"]
  node_sales_ui["Sales and Product UI<br/>[+page.server.ts]"]
  node_product_ops["Product and Stock<br/>[queries.ts]"]
  node_discounts["Discounts<br/>[validate.ts]"]
end

subgraph group_insights["Business Insights"]
  node_dashboard["Dashboard<br/>[+page.server.ts]"]
  node_statistics["Statistics<br/>[loaders.ts]"]
  node_facts_queries["Fact Queries<br/>[queries.ts]"]
  node_analytics["Sales Analytics<br/>[core.ts]"]
  node_facts_math["Fact Calculations<br/>[facts.ts]"]
  node_periods["Period and Time<br/>[period.ts]"]
end

subgraph group_decision["Decision Support"]
  node_simulator["Price Simulator<br/>[simulation.ts]"]
  node_copilot_ui["Copilot Chat<br/>[+server.ts]"]
  node_copilot_tools["Copilot Tools<br/>[summary.ts]"]
  node_llm["LLM Provider"]
end

subgraph group_platform["Accounts and Data"]
  node_receipt_data[("Receipts and Items<br/>[schema.ts]")]
  node_accounts["Authentication and Staff<br/>[auth.ts]"]
  node_business_settings["Business Settings<br/>[+server.ts]"]
end

node_owner(("Owner"))
node_staff(("Staff"))

node_staff -->|"records sales"| node_sales_ui
node_owner -->|"manages sales"| node_sales_ui
node_owner -->|"manages products"| node_product_ops
node_owner -->|"manages discounts"| node_discounts
node_sales_ui -->|"stores receipts"| node_receipt_data
node_owner -->|"reviews KPIs"| node_dashboard
node_owner -->|"reviews reports"| node_statistics
node_statistics -->|"loads facts"| node_facts_queries
node_facts_queries -->|"queries"| node_receipt_data
node_facts_queries -->|"uses calculations"| node_analytics
node_analytics -->|"uses fact math"| node_facts_math
node_periods -.->|"sets report range"| node_statistics
node_owner -->|"tests scenarios"| node_simulator
node_simulator -->|"calculates metrics"| node_facts_math
node_owner -->|"asks questions"| node_copilot_ui
node_copilot_ui -.->|"dispatches tools"| node_copilot_tools
node_copilot_ui -.->|"requests explanations"| node_llm
node_owner -->|"manages staff"| node_accounts
node_owner -->|"updates identity"| node_business_settings
node_business_settings -.->|"sets business timezone"| node_periods

click node_sales_ui "https://github.com/itsflaid/katalyst/blob/main/src/routes/transactions/%2Bpage.server.ts"
click node_product_ops "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/products/queries.ts"
click node_discounts "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/discounts/validate.ts"
click node_receipt_data "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/db/schema.ts"
click node_dashboard "https://github.com/itsflaid/katalyst/blob/main/src/routes/dashboard/%2Bpage.server.ts"
click node_statistics "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/stats/loaders.ts"
click node_facts_queries "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/facts/queries.ts"
click node_analytics "https://github.com/itsflaid/katalyst/blob/main/src/lib/analytics/core.ts"
click node_facts_math "https://github.com/itsflaid/katalyst/blob/main/src/lib/analytics/facts.ts"
click node_periods "https://github.com/itsflaid/katalyst/blob/main/src/lib/shared/period.ts"
click node_simulator "https://github.com/itsflaid/katalyst/blob/main/src/lib/simulation.ts"
click node_copilot_ui "https://github.com/itsflaid/katalyst/blob/main/src/routes/copilot/chat/%2Bserver.ts"
click node_copilot_tools "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/copilot/tools/summary.ts"
click node_accounts "https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/auth/auth.ts"
click node_business_settings "https://github.com/itsflaid/katalyst/blob/main/src/routes/api/business/%2Bserver.ts"

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_sales_ui,node_product_ops,node_discounts toneBlue
class node_dashboard,node_statistics,node_facts_queries,node_analytics,node_facts_math,node_periods toneAmber
class node_simulator,node_copilot_ui,node_copilot_tools,node_llm toneMint
class node_receipt_data,node_accounts,node_business_settings toneRose
class node_owner,node_staff toneIndigo
```

## Components

### Sales and Catalog

- [Sales and Product UI](https://github.com/itsflaid/katalyst/blob/main/src/routes/transactions/%2Bpage.server.ts): `src/routes/transactions/+page.server.ts`
- [Product and Stock](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/products/queries.ts): `src/lib/server/domains/products/queries.ts`
- [Discounts](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/discounts/validate.ts): `src/lib/server/domains/discounts/validate.ts`

### Business Insights

- [Dashboard](https://github.com/itsflaid/katalyst/blob/main/src/routes/dashboard/%2Bpage.server.ts): `src/routes/dashboard/+page.server.ts`
- [Statistics](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/stats/loaders.ts): `src/lib/server/domains/stats/loaders.ts`
- [Fact Queries](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/facts/queries.ts): `src/lib/server/domains/facts/queries.ts`
- [Sales Analytics](https://github.com/itsflaid/katalyst/blob/main/src/lib/analytics/core.ts): `src/lib/analytics/core.ts`
- [Fact Calculations](https://github.com/itsflaid/katalyst/blob/main/src/lib/analytics/facts.ts): `src/lib/analytics/facts.ts`
- [Period and Time](https://github.com/itsflaid/katalyst/blob/main/src/lib/shared/period.ts): `src/lib/shared/period.ts`

### Decision Support

- [Price Simulator](https://github.com/itsflaid/katalyst/blob/main/src/lib/simulation.ts): `src/lib/simulation.ts`
- [Copilot Chat](https://github.com/itsflaid/katalyst/blob/main/src/routes/copilot/chat/%2Bserver.ts): `src/routes/copilot/chat/+server.ts`
- [Copilot Tools](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/copilot/tools/summary.ts): `src/lib/server/domains/copilot/tools/summary.ts`
- **LLM Provider**

### Accounts and Data

- [Receipts and Items](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/db/schema.ts): `src/lib/server/db/schema.ts`
- [Authentication and Staff](https://github.com/itsflaid/katalyst/blob/main/src/lib/server/domains/auth/auth.ts): `src/lib/server/domains/auth/auth.ts`
- [Business Settings](https://github.com/itsflaid/katalyst/blob/main/src/routes/api/business/%2Bserver.ts): `src/routes/api/business/+server.ts`

### Other components

- **Owner**
- **Staff**

## Connections

- Staff → Sales and Product UI: records sales
- Owner → Sales and Product UI: manages sales
- Owner → Product and Stock: manages products
- Owner → Discounts: manages discounts
- Sales and Product UI → Receipts and Items: stores receipts
- Owner → Dashboard: reviews KPIs
- Owner → Statistics: reviews reports
- Statistics → Fact Queries: loads facts (evidence: `src/lib/server/domains/stats/loaders.ts`)
- Fact Queries → Receipts and Items: queries (evidence: `src/lib/server/domains/facts/queries.ts`)
- Fact Queries → Sales Analytics: uses calculations (evidence: `src/lib/server/domains/facts/queries.ts`)
- Sales Analytics → Fact Calculations: uses fact math (evidence: `src/lib/analytics/core.ts`)
- Period and Time → Statistics: sets report range
- Owner → Price Simulator: tests scenarios
- Price Simulator → Fact Calculations: calculates metrics (evidence: `src/lib/simulation.ts`)
- Owner → Copilot Chat: asks questions
- Copilot Chat → Copilot Tools: dispatches tools
- Copilot Chat → LLM Provider: requests explanations
- Owner → Authentication and Staff: manages staff
- Owner → Business Settings: updates identity
- Business Settings → Period and Time: sets business timezone
