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

# Architecture

## How the system is structured

StreamWage is built across two contracts that work together: a factory that handles deployment, and a core payroll contract that handles everything else. Understanding how they relate is key to understanding the upgrade strategy.

***

## The deployment pattern

The system uses a beacon proxy pattern from OpenZeppelin. When a wallet calls `deployPayroll()` on the factory, they get their own isolated payroll contract, their own state, their own workers, their own treasury. But under the hood, all of these contracts share one implementation.

That shared implementation lives behind a beacon. Every proxy, before executing any logic, asks the beacon: *"where is the current implementation?"* The beacon points them to it. This means upgrading the entire system is a single transaction, update the beacon, and every proxy instantly runs the new logic.

*<mark style="color:blue;">Each wallet gets a fully independent contract with isolated state. No wallet can see or touch another wallet's workers or funds.</mark>*

***

## Diagram

```mermaid
flowchart TD
    A[StreamWagePayrollFactory] -->|creates| B[UpgradeableBeacon]
    A -->|deploys| C[BeaconProxy — wallet A]
    A -->|deploys| D[BeaconProxy — wallet B]
    C -->|asks beacon for implem| B
    D -->|asks beacon for impl| B
    B -->|points to| E[StreamWagePayroll implementation]
```

***

## Why the beacon proxy?

This was a deliberate tradeoff. The beacon pattern introduces a centralized upgrade authority, whoever owns the beacon can push a new implementation to every proxy at once. That is a real power, and it means users are trusting the beacon owner.

The reason this tradeoff was accepted: StreamWage is an evolving system. If a bug is found, the beacon allows a fix to be deployed instantly across every instance rather than requiring every wallet to migrate to a new contract manually. It also means new features can be rolled out without disrupting existing deployments.

*<mark style="color:blue;">The beacon owner has upgrade authority over all proxies. This is a known and intentional centralization point, accepted in exchange for fast bug fixes and forward upgrades.</mark>*

***

## How deployment works

The factory's constructor does two things when it is first deployed: it deploys the implementation contract and creates the beacon pointing to it. After that, any wallet can call `deployPayroll(address initialOwner)` to get their own proxy, initialized with their chosen owner address.

The factory emits a `PayrollDeployed` event on every deployment, recording the new contract address, its owner, and who triggered the deployment , so the full deployment history is always queryable on-chain.


---

# 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://alameen.gitbook.io/streamwage/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.