Merge pull request #26 from opensource-observer/docs/hackathon

docs: architecture and implementation plan

apps/docs/docs/how-kariba-works/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Learn How Kariba Works",
+  "position": 4,
+  "link": {
+    "type": "doc",
+    "id": "index"
+  }
+}

apps/docs/docs/how-kariba-works/architecture.md

@@ -0,0 +1,64 @@
+---
+title: Network Architecture
+sidebar_position: 5
+---
+
+[![](https://mermaid.ink/img/pako:eNp9lE1v2zAMhv-KoHOD3nMYkC3dUHRZgmbbpd5BkRlHq00ZlJQsKPrfR1tyErlB7Is-HpF6X9J-k9qWIKdyMpkU6I2vYSoKyS_2KwVua3vQO0VefH8uUPDjwqYi1e6EdfalkMsWUKxtIA1iuXFAe6BC_ols96jWdNh6KWZtK-7FbPWY7bemhdogMDRXXp3mGWSwhH9AA5OmLk-Eqj467xiapeG1GGIyYYkrshocAzz9dM754VaJtodOVc-yno85I7ZgM-urIQHLkXvaNk1A44983QdtHUeBJrvv3nqWyNvfLHuKCtnhe_G7X81AT6BcoCyS-JkWc6_J_gXdW7RKw2w_uJjxlxvnGE5GoZ-DqcsktD8zChGpZ9gDBkjccMuRIWxnpB9xa6lJcNQ-IhbgyehTzWxtdIo2xI7c14DD5VQF6COTK1j0B4a7pdaI4IWCG1Se8gYYpdzERq3xqshsFJfhqR-IH-APll7zevTquzr2A_GA1fib6bW_RDsMVsmLS0Jb9KRiPyyRP3OD57Ur6aKIuaHYOGOHT0kj98Xi1lQsd0DPofMWuHRoRbAFAu71a3U-RTgX-oQN_dyB8k42QI0yJf_b3rqlQvodNGxQ938rVedmge_MqeDt-ohaTj0FuJNkQ7WT062qHc9CWyoPc6O4Mk1aff8PNmWg1g?type=png)](https://mermaid.live/edit#pako:eNp9lE1v2zAMhv-KoHOD3nMYkC3dUHRZgmbbpd5BkRlHq00ZlJQsKPrfR1tyErlB7Is-HpF6X9J-k9qWIKdyMpkU6I2vYSoKyS_2KwVua3vQO0VefH8uUPDjwqYi1e6EdfalkMsWUKxtIA1iuXFAe6BC_ols96jWdNh6KWZtK-7FbPWY7bemhdogMDRXXp3mGWSwhH9AA5OmLk-Eqj467xiapeG1GGIyYYkrshocAzz9dM754VaJtodOVc-yno85I7ZgM-urIQHLkXvaNk1A44983QdtHUeBJrvv3nqWyNvfLHuKCtnhe_G7X81AT6BcoCyS-JkWc6_J_gXdW7RKw2w_uJjxlxvnGE5GoZ-DqcsktD8zChGpZ9gDBkjccMuRIWxnpB9xa6lJcNQ-IhbgyehTzWxtdIo2xI7c14DD5VQF6COTK1j0B4a7pdaI4IWCG1Se8gYYpdzERq3xqshsFJfhqR-IH-APll7zevTquzr2A_GA1fib6bW_RDsMVsmLS0Jb9KRiPyyRP3OD57Ur6aKIuaHYOGOHT0kj98Xi1lQsd0DPofMWuHRoRbAFAu71a3U-RTgX-oQN_dyB8k42QI0yJf_b3rqlQvodNGxQ938rVedmge_MqeDt-ohaTj0FuJNkQ7WT062qHc9CWyoPc6O4Mk1aff8PNmWg1g)
+
+
+## Actor Overview
+
+### Kariba
+
+#### Policy Engine
+
+The policy engine defines the funding policy for the program.
+It takes as input, preferences from the community (e.g. governance votes)
+and metrics as measured by OSO,
+and produces a funding schedule to the funding agent.
+
+Some example policies we could take inspiration from:
+- **linear**
+    - users directly choose how much projects get (e.g. Optimism RF3)
+- **quadratic** - users influence quadratic funding (e.g. Gitcoin matching funds)
+- **metric funding** - users choose which metrics are worth funding, which generates a project funding schedule (e.g. Optimism RF4)
+
+### Funding agent / contracts
+
+The policy engine should produce a funding schedule, that defines how much
+each project receives per funding period.
+The funding agent takes the schedule and allocates funding into onchain
+contracts for the projects to claim.
+Funding agents are often empowered by an ecosystem treasury,
+but in theory anyone could contribute to a funding pool.
+
+### Ecosystem
+
+#### Projects / Users
+
+Developers build applications, services, and experiences for users,
+which bring revenue to the ecosystem.
+The goal is to fund the work that best delivers value to users
+and increases revenue for the ecosystem.
+In crypto, this usually comes in the form of transaction fees,
+but any revenue can work (including enterprise sales).
+
+#### Goverance
+
+The primary purpose of governance in this model is to define
+what "good" looks like.
+Good will look different in every ecosystem,
+and embodies a unique combination of goals and strategy
+into a North Star for the entire ecosystem.
+
+### Open Source Observer
+
+OSO serves as the measurement infrastructure across the entire
+ecosystem, measuring governance, project activity,
+user behavior, and financial flows.
+As an open source, open data, open infrastructure data pipeline,
+a public community of data scientists and engineers evolve the
+data models, insights, and metrics, 
+used for better governance.
+
+

apps/docs/docs/how-kariba-works/implementation.md

@@ -0,0 +1,119 @@
+---
+title: Implementation
+sidebar_position: 6
+---
+
+:::warning
+These are very preliminary thoughts for the purposes of a prototype.
+All of this is likely to change very quickly.
+:::
+
+## Product Overview
+
+### Goals
+
+- **Simple**: The application should be simple enough for the average delegate/voter to do without hand-holding
+- **Low overhead**: We want to reduce the amount of work a voter needs to do to get quality results.
+- **Composable**: We want to be able to replace different modules as necessary to easily evolve with the community.
+
+## Users
+
+1. **Admin** - has the power to create/edit/cancel a funding pool.
+2. **Funder** - wants to contribute financial resources to a funding pool.
+3. **Project** - wants to be rewarded for impact
+
+## Flows
+
+### Create a funding pool
+
+For a program with many badgeholders,
+they would each get their own funding pool allocation
+
+1. Admin logs in
+2. Admin fills out a form with: name, description, funding schedule (start/end/frequency), funding cap per period, minimum number of projects.
+3. Admin creates funding pool
+4. Funding pool is shareable via link
+
+### Email
+
+#### Funding review
+
+Before the end of the funding period when settlement happens,
+admins will get an email overview with:
+- Total funding going out
+- Which projects will be funded and by how much (with diffs against previous period)
+- Link to confirm/authorize the distribution
+
+They will be redirected to the application where they can:
+- Edit the metric weights for how allocations are determined
+- Edit/remove any project allocation
+- Scale up/down the total distribution for this period
+- Confirm the transaction to authorize the spending
+
+#### General notifications
+- Warnings if there aren't enough projects participating before the start date
+- Warnings if the funding pool is low on funds
+- Notifications if the funding pool is starting / ending
+
+### Edit a funding pool
+
+1. Admin views all of their funding pools in a dashboard
+2. Admin can go in and edit any funding pool (e.g. metric weights)
+3. Admin gets to see who funded their funding pool
+4. Admin sees all registered projects and their allocation for the next distribution.
+
+### Contribute to a funding pool
+
+1. Funder gets a share link for a funding pool.
+2. Funder can see how the funding pool is configured and a history of distributions
+3. Funder enters how much to fund the pool.
+4. Funder sends a transaction to add funds.
+
+### Register your project
+
+1. Project logs in with GitHub.
+2. Create a project
+3. Enter a destination wallet address.
+4. Enter their oss-directory `project_name`.
+
+### Project applies for a funding pool
+
+1. Project receives a share link from the funding pool admin
+2. Project clicks "Register".
+
+### Project withdraws funds
+
+1. Project can see all funding pools they are apart of
+2. Project can see their total balance
+3. Project can withdraw their balance to designated wallet
+
+### Analytics
+
+Admin can see:
+- How much they've funded across all projects
+- What other funding these projects have gotten
+
+Funder can see:
+- Total they've distributed across all projects over all funding pools.
+
+Projects can see:
+- How much they've received and from which funding pools
+
+## Components
+
+### Frontend
+
+Propose we get running with a simple Next.js application + Plasmic + Supabase.
+We can no-code most of the application surfaces
+
+### SDK
+
+This would wrap some other funding primitive (e.g. 0xSplits SDK)
+and complete the actions above, including:
+
+- Create funding pool
+- Edit funding pool
+- Authorize distribution
+- Cancel funding pool
+
+We can import these functions into Plasmic for use.

apps/docs/docs/how-kariba-works/index.mdx

@@ -0,0 +1,4 @@
+---
+title: Kariba Overview
+sidebar_position: 0
+---