@@ -0,0 +1,129 @@
1++++
2+
3+title = "Expense Sharing App"
4+date = "2023-06-22"
5+
6+[taxonomies]
7+grant_type = ["Proposal"]
8+grant_category = ["App Dev"]
9+
10+[extra]
11+image = ""
12+description = ""
13+reward = "1 Star"
14+assignee = ["~talfus-laddus"]
15+champion = [""]
16+grant_id = "P0279"
17+completed = false
18+canceled = false
19+
20++++
21+
22+# Motivation
23+The Urbit community hosts many IRL events and, inevitably, this means splitting tabs with other Urbiters. Urbit needs its own expense sharing app that seamlessly keeps track of all expenses and IOUs in one place and works with both crypto and fiat [RFP](https://urbit.org/grants/splitwise-rfp).
24+
25+Urbit is for small communities. And those need a way to keep track of and to split shared expenses.
26+
27+# Basic User Story
28+A member of a group wants to keep track of all expenses in order to eventually settle debts with a minimal number of transactions.
29+
30+# Basic User Tasks
31+ - Create or select a group
32+ - Invite other people to the group
33+ - Add an expense involving other group members
34+ - View all expenses
35+ - Edit an expense
36+ - Delete an expense
37+ - Retrieve a suggestion on how to balance debts with minimal number of transactions
38+
39+# Basic User Flow
40+1. Select a group
41+2. Add an expense
42+3. Check balance
43+ - Who is owed, and who owes money to the group and how much?
44+4. Settle debts
45+ - The app suggests an efficient way to settle debts in the group
46+ - Mark outstanding expenses as paid
47+
48+# Architecture
49+The architecture will be loosely modeled on existing expense sharing apps such as [Splitwise](https://www.splitwise.com/) and [Tricount](https://www.tricount.com/en/).
50+
51+An expense can involve only a subset of all group members. It has the following attributes:
52+
53+- title (For what reasons?)
54+ - payer (Who paid?)
55+ - involves (For whom?)
56+ - date (When?)
57+ - amount (How much?)
58+ - currency
59+ - note
60+
61+All group members are ships (`@p`). A list of group members and all expenses of the group will be stored on the ship of the group initiator. Other group members will read and write from/to there.
62+
63+In order to find a minimum number of transaction to settle debts in the group ("simplified debts"), shared expenses will be modeled as a flow network. Money flows from the participants who owe money to the group (debitors) to the participants who are owed money by the group (creditors). Using [Edmonds–Karp algorithm](https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm), the [maximum flow](https://en.wikipedia.org/wiki/Maximum_flow_problem) of this network will be computed. From the resulting residual network transactions to balance out shared expenses will be derived. A Python reference implementation can already be found [here](https://git.sr.ht/~talfus-laddus/splt-exps-py).
64+
65+*Note: The trivial case of settling debts among two person (group size of two) is of course supported.*
66+
67+# Backend
68+The backend will be a gall agent with a basic set of operations addressing the user's needs listed above. Alongside the gall agent, a couple of libraries will be created: A library implementing the Edmonds-Karp algorithm and a library handling currency exchange rates and conversions.
69+
70+# Frontend
71+[Keep it simple, stupid!](https://en.wikipedia.org/wiki/KISS_principle)
72+The frontend will be a mobile-first website.
73+
74+It is an open question whether the frontend will in the initial phase be served from Mars or Earth. The website should eventually be served from the ship.
75+
76+# Milestones
77+Documentation and tests throughout the code base will be present. The source code will be available in a public git repository and licensed under MIT.
78+
79+## Milestone 1 - Proof of Concept
80+Completion: Beginning of App School Live (August 2023)
81+
82+Payment: None
83+
84+Deliverables: Edmonds-Karp Library
85+
86+The Proof of Concept (POC) demonstrates how to model shared expenses as a flow network and how to derive from it the minimum number of transactions needed to settle debts. The POC implements the Edmonds-Karp algorithm as well as the logic of how to construct the flow network from a list of expenses and how to derive a list of transactions from the residual network.
87+
88+## Milestone 2 - Minimal Viable Product
89+Completion: End of App School Live before Assembly (October 2023)
90+
91+Payment: 1 Star
92+
93+Deliverables : Gall Agent: Website
94+
95+The Minimal Viable Product (MVP) consists of a gall agent as backend and a website as frontend.
96+
97+Iterations
98+1. Create a gall agent containing a basic set of operations to manage groups and to add, store, delete and retrieve group expenses.
99+2. Create a simple, stupid and mobile-first website as an interface to the gall agent.
100+3. Add a feature to “simplify debts” by integrating the Edmonds-Karp library into the gall agent. The agent can suggest a way to balance out shared expenses with a minimal number of transactions.
101+4. Synchronize expenses among the group members.
102+5. Handle different currencies. Retrieve the current exchange rate and do conversions between currencies.
103+6. Make the app available through Software Distribution.
104+
105+# Limitations
106+Since the list of expenses is stored on the group initiator's ship, when it is down other people can not synchronize their state of the application.
107+
108+# Additional Future Work
109+The future of the app could entail:
110+
111+ - A robust decentralization/synchronization mechanism which addresses the limitation raised above
112+ - A more polished interface
113+ - An integration into Groups
114+ - Apps for Android and iOS
115+ - A new feature to categorize expenses and derive statistics
116+ - Yet unforeseen improvements
117+
118+# About Me
119+I am in search of something worthwhile to contribute my time and effort to.
120+
121+My name is Matthias Schaub (`~talfus-laddus`). Even though I work part-time as a software developer for a non-profit corporation dedicated to better society and environment, I feel the need to spend my time on projects of which I am more confident that they provide sustained value to society (or at least have the potential to). That is why I am invested to contribute to the Urbit ecosystem by learning Hoon and how to build applications on Urbit. A more basic motivation is to have my flat mates on Urbit. Beside a chat, we need a way to handle shared expenses.
122+
123+I attended Hoon School and registered for App School. Alongside the App School curriculum, I want to foster my learning by building this application. On Earth side I have solid Python and basic HTML, CSS, and JavaScript skills. I am proficient in git, and I am used to working with a terminal on a Linux machine. In the past, I wanted to read the reference of a Hoon rune without leaving Vim. So I wrote a Python script to convert Hoon rune references from Markdown to Vimdoc. The result is a Vim helpfile in disguise of a plugin ([hoon-runes.vim](https://git.sr.ht/~talfus-laddus/hoon-runes.vim)). Shortly after, I did the same for the documentation of the Hoon standard library ([hoon-stdlib.vim](https://git.sr.ht/~talfus-laddus/hoon-stdlib.vim)).
124+
125+In order to find out more about my previous works:
126+ - [Personal website](https://talfus-laddus.de/)
127+ - [Sourcehut](https://git.sr.ht/~talfus-laddus)
128+ - [GitHub](https://github.com/matthiasschaub)
129+