# agoric/dapp-offer-up architecture

> Architecture diagram of the GitHub repository agoric/dapp-offer-up, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agoric/dapp-offer-up
- Repository: https://github.com/agoric/dapp-offer-up

## Overview

The project is an Agoric decentralized application (Dapp) called “Offer Up” built on the Agoric smart contract platform. It features a smart contract component that runs on an Agoric blockchain and a user interface built with React, with additional support files (e.g., API stubs, testing utilities, and deployment configurations) arranged across several directories.

##### Main Components
- Smart Contract Layer: Located in the “contract” directory, this component holds the Agoric smart contract logic, accompanying scripts (such as deployment and proposal management), and tests. It is the core business logic that handles creating offers using in-app currency (IST).
- User Interface (UI) Layer: Found under the “ui” directory, this part of the project uses React (and likely Vite for bundling) to present the marketplace to the user. It connects with the smart contract and integrates with the Agoric wallet.
- Blockchain/Agoric Environment: The project uses a local Agoric blockchain, initiated via Docker (as indicated by the docker-compose.yml file and instructions from the README) and configured through files in the “_agstate” folder for Agoric server setups.
- API (Optional/Experimental): There’s an “api” folder with its own package.json and a README, suggesting that this might serve to abstract or provide additional endpoints, even if not the primary focus of the Dapp.
- Development/CI/CD and Testing Infrastructure: With configuration in folders like “.github/workflows” (for GitHub Actions), test directories in “contract/test” and “ui/test”, along with scripts (e.g., update-dependencies.js), these support development, continuous integration, and automated testing.

##### Relationships & Interactions
- The smart contract is deployed onto and executed within the Agoric blockchain environment (managed via Docker). Mark the chain as an external system/container that interacts with the contract.
- (Optional) If the API is actively used, it may serve as an intermediary between the external world or add layers of abstraction on top of the blockchain interactions.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project cleanly separates the smart contract logic (“contract” directory) from the UI (React-based “ui” directory) and deployment/testing scripts.
- Containerization & Development Environment: Use of Docker and development configurations (e.g. in “.devcontainer” and “docker-compose.yml”) demonstrates that the project is built with containerized, isolated environments to mirror the blockchain.
- Modular Design: Multiple package.json files and segregated test folders denote a modular approach, making each segment (smart contract, UI, API) independently manageable and testable.
- Extensibility & Automation: The inclusion of CI/CD workflows (GitHub Actions) and testing setups indicates a strong emphasis on automated testing and integration.

##### Specify Relevant Technologies, Frameworks, and Tools
- Agoric Framework for smart contracts.
- Docker and docker-compose for local blockchain environment management.
- React for the user interface with Vite for development/build processes.
- Yarn for dependency management.
- Testing tools for both unit and end-to-end testing (likely Jest/AVA for contract tests and Synpress for UI e2e tests).
- GitHub Actions for CI/CD workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Layer
  subgraph "Frontend Layer"
    UI["React UI (ui)"]:::ui
    Wallet["Keplr Wallet"]:::external
  end

  %% Smart Contract Layer
  subgraph "Smart Contract Layer"
    SmartContract["Agoric Smart Contracts (contract)"]:::contract
    SmartContractTests["Contract Tests (contract/test)"]:::testing
  end

  %% Backend/API Layer
  subgraph "Backend/API Layer"
    APIService["Optional API Service (api)"]:::api
  end

  %% Blockchain / Agoric Environment
  Blockchain["Agoric Blockchain Environment (_agstate)"]:::blockchain

  %% Development & CI/CD and Containerization
  subgraph "Development & CI/CD"
    CICD["CI/CD (.github/workflows)"]:::ci
    UITests["UI Tests (ui/test)"]:::testing
    DevContainer["Dev Container (.devcontainer)"]:::dev
  end

  %% Interactions
  UI -->|"submitsOffers"| SmartContract
  SmartContract -->|"deployedOn"| Blockchain
  UI -->|"authenticatesWith"| Wallet
  UI -->|"callsAPI"| APIService
  APIService -->|"abstractsCallsTo"| SmartContract

  %% Styles
  classDef ui fill:#bbf,stroke:#000,stroke-width:2px;
  classDef contract fill:#fbb,stroke:#000,stroke-width:2px;
  classDef blockchain fill:#bfb,stroke:#000,stroke-width:2px;
  classDef api fill:#ff9,stroke:#000,stroke-width:2px;
  classDef external fill:#efe,stroke:#065,stroke-width:2px;
  classDef ci fill:#f9f,stroke:#000,stroke-width:2px;
  classDef testing fill:#ddd,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;
  classDef dev fill:#cfc,stroke:#333,stroke-width:2px;

  %% Click Events
  click UI "https://github.com/agoric/dapp-offer-up/tree/main/ui/"
  click SmartContract "https://github.com/agoric/dapp-offer-up/tree/main/contract/"
  click Blockchain "https://github.com/agoric/dapp-offer-up/tree/main/_agstate/"
  click APIService "https://github.com/agoric/dapp-offer-up/tree/main/api/"
  click CICD "https://github.com/agoric/dapp-offer-up/tree/main/.github/workflows/"
  click SmartContractTests "https://github.com/agoric/dapp-offer-up/tree/main/contract/test/"
  click UITests "https://github.com/agoric/dapp-offer-up/tree/main/ui/test/"
  click DevContainer "https://github.com/agoric/dapp-offer-up/tree/main/.devcontainer/"
```
