<!-- MIT License. Copyright (c) 2026 Decentralized Science Labs LLC. -->
<!-- summary: Where to start with COLLAB's code: the repository, the toolchain (Foundry, Python, no Node.js), memory notes, the project's rules and the licences. -->
# Developer overview

This is the starting point for developers who read, test, extend or integrate with COLLAB: what the repository holds, the tools it needs, how to keep builds within a small machine's memory, where to begin for each kind of work, and under which licences everything ships. COLLAB 2.2 is an alpha: its contracts and server kit had AI-assisted internal reviews and no external audit, so treat them as such when you build on them.

## What COLLAB is made of

- **Contracts** in Solidity on GenesisL1 (EVM chain 29, coin L1): a factory that creates each DAO as six clones, shared protocol contracts, the DeSciFi exchange and two read-only lenses. Owner-less and not upgradeable.
- **A static web app**: HTML, CSS and ES modules served as files, reading the chain in the browser and writing through the visitor's wallet. No bundler, no framework.
- **A server kit** for Debian and Ubuntu: an installer for nginx with HTTPS, an admin service in Python's standard library, and a prerender job that writes static pages and cache files.
- **Tooling** in Python: a local chain, sandboxes, a dev server, exporters, the prerender, the docs build, the release build and the end-to-end tests.

[Architecture](ARCHITECTURE.md) shows how they fit together.

## The repository

| Path | Holds |
|---|---|
| `contracts/` | `core/` (DAOFactory, DAOGovernor, DAOTreasury, ShareToken, DAOPolicy, DAOProfile, PolicyBuilder), `cipnft/` (CipherVault), `tokens/` (DAOToken, TokenLauncher, MemberDistributor), `descifi/` (DeSciFiFactory, DeSciFiPair, DeSciFiRouter, LockFactory and LockBox), `storage/` (TextStore, CollabKeyring), `lens/` (DAOLens, MarketLens), `interfaces/`, `utils/` (Utf8, Png, StoredBytes) |
| `test/` | the Foundry suite: unit and integration tests, `invariants/`, `audit/` (the reviews' proof-of-concept tests), `mocks/`, `utils/` |
| `script/` | `Deploy.s.sol` (every network), `SeedDemo.s.sol` (local demo data), `integrations.json` (the default GL1F collections and CIPNFT contracts on chain 29), `assets/` (the demo DAOs' logos) |
| `externals/` | pinned copies of the GenesisL1 contracts COLLAB integrates with (CIPNFT, GL1F, GL1F Crypto): `src/` and their compiled `bin/` |
| `lib/` | OpenZeppelin Contracts and Contracts Upgradeable 5.1.0, Solady 0.1.26, forge-std 1.9.4 |
| `abi/` | one ABI file per contract, exported from the build, for integrators |
| `web/` | the app; [The web app](../web/DEVELOPING.md) is its reference |
| `server/` | `install.sh`, `admin/collab_admin.py`, the `nginx/` templates, the `systemd/` units, `bin/collab` (the helper) and `tests/` |
| `deploy/` | nginx and Caddy configurations for hosting without the server kit, `sync_csp.py`, `check_site.py` |
| `tools/` | the Python tooling, with `e2e/` (browser tests), `seo/` (the prerender's modules) and `tests/` |
| `docs/` | this documentation, as Markdown; the page registry is in `tools/build_docs.py` |
| `deployments/` | deployment records, one per chain id (`29.json` for GenesisL1, once COLLAB is deployed there; 2.2.0 ships none), and, never released, the local chain's files |

At the top: `foundry.toml`, `remappings.txt`, `README.md`, `LICENSE` and `THIRD_PARTY_NOTICES.md`.

## The toolchain

| Part | Tools |
|---|---|
| Contracts | Foundry (`forge`, `cast`, `anvil`) with solc 0.8.28, via-IR, optimizer 200 runs, EVM `istanbul` (no PUSH0, MCOPY or transient storage), IPFS metadata hash. `remappings.txt` is the only remapping source (`auto_detect_remappings = false`), so the trimmed libraries of the release archive compile to the same bytecode, metadata included |
| Offline builds | `forge build --offline --use /path/to/solc-0.8.28`; the release build passes `FORGE_FLAGS` to every forge call |
| Upstream contracts | solc 0.8.20 with their own settings, only when they change (`tools/build_externals.py`) |
| Tooling | Python 3.10 or later: the standard library, plus Pillow for images and pycryptodome (or OpenSSL 3.2 or later) for keccak-256 in the prerender. The admin service and the config writer use the standard library only. Building a release needs Python 3.11.4 or later ([Building a release](release-build.md#before-you-build)) |
| Browser tests | Playwright for Python with Chromium |
| Server | bash, apt, nginx, certbot, systemd, OpenSSL |
| Browser libraries | committed files with their version in the name: ethers 6.17.0, markdown-it 14.1.0, libsodium.js 0.8.2, mlkem-wasm 0.0.7 |

There is no Node.js anywhere: no npm, no bundler, no transpiler, no package to install for the site. [Local development](local-development.md) has the installation commands.

## Memory notes

- A first `forge build` of everything compiles with via-IR in one solc run, which can need more than 5 GB of memory. Build the contracts first (`forge build --skip test --skip script`), then a few test files per `forge build` call; that stays well under 2 GB and gives the same artifacts. `tools/build_release.py` compiles in batches of four files (`FORGE_BATCH`).
- `forge test` after the batched builds needs no further compilation.
- The end-to-end runner starts one Chromium and opens a context per browser; on a small machine, run one suite at a time.
- A sandbox is one anvil and one Python dev server; stop yours when you are done (`dev_sandbox.py down`).

## Where to start

| You want to | Read | Then |
|---|---|---|
| understand the system | [Architecture](ARCHITECTURE.md) | [Contracts guide](contracts.md) |
| run it on your machine | [Local development](local-development.md) | [The web app](../web/DEVELOPING.md) |
| change a contract | [Contracts guide](contracts.md), [Governance internals](governance-internals.md) | the tests in `test/`, the [Gas reference](gas.md), then the exporters (`tools/export_abis.py`, `tools/abi_summary.py`, `tools/export_deploy_artifacts.py`) |
| add a proposal builder | [The web app](../web/DEVELOPING.md#proposal-builders) | `contracts/core/PolicyBuilder.sol`, [Governance internals](governance-internals.md#the-115-default-rules) |
| change a page or a view | [The web app](../web/DEVELOPING.md) | `python3 tools/lint_web.py`, the suite of that area in [Testing](testing.md) |
| read COLLAB from your own code | [Reading COLLAB from the chain](reading-the-chain.md) | [Data formats](data-formats.md), `abi/`, [Contract API reference](CONTRACT_API.md) |
| work on the server kit | [Admin API reference](admin-api.md), [Data formats](data-formats.md) | [Installing COLLAB on a server](INSTALL.md), `server/tests/` |
| write or run tests | [Testing](testing.md) | [Local development](local-development.md#private-sandboxes) |
| cut a release | [Building a release](release-build.md) | [Release notes](RELEASE_NOTES.md) |
| write documentation | [The web app](../web/DEVELOPING.md#the-docs-pages) | `python3 tools/build_docs.py --check` |

## The project's rules

- No Node.js anywhere in what COLLAB builds or ships.
- Every source file starts with the licence line `MIT License. Copyright (c) 2026 Decentralized Science Labs LLC.`, in the comment form of its language; Solidity files use `// SPDX-License-Identifier: MIT` and a copyright line instead ([The web app](../web/DEVELOPING.md#non-negotiable-rules) gives each form). Vendored files keep their own. `tools/lint_web.py` checks `web/` and `tools/`.
- No new third-party code without a licence check, recorded in `THIRD_PARTY_NOTICES.md`.
- `python3 tools/lint_web.py` reports 0 errors, and every generated file is current (its `--check`).
- Releases ship as one `.tar.gz` archive with checksums.
- Security statements stay honest: the reviews are AI-assisted and done apart from the implementation, and there has been no external audit.

## Licences

COLLAB, its contracts, the web app, the server kit, the tools and this documentation, is open source under the MIT License, copyright 2026 Decentralized Science Labs LLC (`LICENSE`). The third-party parts keep their own licences:

| Component | Licence |
|---|---|
| OpenZeppelin Contracts 5.1.0 and Contracts Upgradeable 5.1.0, Solady 0.1.26 | MIT |
| forge-std 1.9.4 (tests and scripts only) | MIT or Apache-2.0 |
| ethers.js 6.17.0, markdown-it 14.1.0 (with its bundled libraries; entities is BSD-2-Clause) | MIT |
| libsodium.js 0.8.2 | ISC |
| mlkem-wasm 0.0.7 (mlkem-native: Apache-2.0 OR ISC OR MIT) | MIT |
| Inter, JetBrains Mono, Source Serif 4 | SIL Open Font License 1.1 |
| the CIPNFT, GL1F and GL1F Crypto contracts in `externals/` | MIT, Decentralized Science Labs |

`THIRD_PARTY_NOTICES.md` lists each with its version, where it lives and its licence file; [Licence and third-party code](license.md) summarises them.

## Related

- [Architecture](ARCHITECTURE.md): the system in one page.
- [Local development](local-development.md): set up your machine.
- [Contracts guide](contracts.md): the Solidity side.
- [The web app](../web/DEVELOPING.md): the browser side.
- [Testing](testing.md): the suites and checks.