Our development docs have some documentation about the project structure but it would also be helpful to have some notes about specific technical choices that were made and why. Examples could include: libraries that are used extensively (for things like component library, state management, localization, and routing), build tooling, release management, etc.

Probably makes most sense to create a separate document for this stuff (something like ARCHITECTURE.md)

Create Button following CoMapeo Mobile's design. Button should use Material UI's Button.

Images from CoMapeo

To Do:

• Button look visually similar to CoMapeo Mobile
• Button has props as described below
• Button uses styled() for style overrides

Props

type ColorScheme = 'dark' | 'light' | 'ComapeoBlue';
type Variant = 'contained' | 'outlined' | 'text';
type Size = 'medium' | 'large';

type ButtonProps = {
    // check if it is a MessageDescriptor. If it is a message descriptor translate it using [formatMessage](https://formatjs.io/docs/react-intl/api#formatmessage)
    children: React.ReactNode | MessageDescriptor //https://formatjs.io/docs/react-intl/components#message-descriptor
    color?: ColorScheme;
    disabled?: boolean;
    onPress: () => void;
    size?: Size;
    testID?: string;
    variant?: Variant;
}

Device Naming

• User clicked on 'Get Started'
• User is invited to name their device
• User cannot proceed to CoMapeo without naming their device
• User successfully names their device
• User lands on the Map screen

Todo

• Display screen as designed
• Make 'Add a Name for our device' mandatory field to be able to Add Name
• Do not display tooltip
• Create Add Name button
• Display device name as entered on first screen
• Create Go to Map button
• Display the map screen when clicking the Done button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1069-4606&mode=design&t=7vnK6OIYo99rronU-0

Copydeck

https://docs.google.com/spreadsheets/d/18x135fNGqwryXcBoJGvtNSJJMHuPB48Vp0o1l16UyzY/edit?usp=sharing

Extracted from #18. That PR introduces changes that generally work fine in development, but when building the archive we run into some issues.

Currently, when packaging the app, all packages that are specified as deps are copied over into the packaged application (and live in the node_modules directory). this is built-in behavior of the vite plugin and as of right now, there is no way to change this (see electron/forge#3570). this results in a rather bloated package size because it essentially copies over a good portion of the node_modules directory into the archive when it's not necessary to do so. We'll need to adjust the vite configuration to account for this (which was originally mostly taken from a template that they provide, with some adjustments based on issues i found):

• update the build.rollupOptions.externals field to make sure that only native modules or builtins (e.g. electron) are not bundled
• patch the vite plugin to disable the "copy over all deps" behavior
• make sure that necessary static assets are included when building the app
  • e.g. offline map, default config, drizzle

Project invite

• User was on #3 and clicked on 'Create or join a project'

• User follows flow to create a project

1.1 User not on project

Todo

• Display text box with What is a Project? copy
• Create Create a Project /Start a new CoMapeo Project button
• Create Join a Project/ Join an existing CoMapeo Project button

1.2 User on project

Todo

• Display text box with What is a Project? copy
• Remove Create a Project /Start a new CoMapeo Project button
• Display text box with You are already on a project. To create a new Project you must uninstall and reininstall CoMapeo
• Create Join a Project/ Join an existing CoMapeo Project button

2

Todo

• DisplayEnter a name for the project title
• Create mandatory text field, max 100 characters
• Use usual error message in the text field (@ErikSin maybe add more details here)
• Create Advanced project settings dropdown button
• Display Import config when Advanced project settings is open
• When clicking Import config display file chooser
• Create Create Project button

3

Todo

• Display success message "XXX Project create"
• Create Invite Devices button
• Create Go to Map button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1070-4687&mode=design&t=ypas7TLUlTe7pRjw-0

Copydeck

https://docs.google.com/spreadsheets/d/1kpoU-mr-fJyxbAxERqrhC2IyRd3T64YEs8fUDzbAFQY/edit?usp=sharing

No project/ Sync

• User first opens the app, they are on an unnamed unofficial project by themselves.
• let them know that they won’t be able to sync their observations until they create or join a project.

Todo

• Display text box with copy You won’t be able to share observations collected yet. To sync and share with other devices
• Create Create or Join a Project button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1200-69&mode=design&t=xfOwkkUA7kBhB7vK-0

Copydeck

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1197-17493&mode=design&t=ojmacHaDmI1ARJ5k-0

Using electron@30, we get the following error when attempting to use @mapeo/core in the main process (technically in the utility process):

/Users/andrewchou/GitHub/digidem/comapeo-desktop/node_modules/@mapeo/crypto/lib/key-utils.js:43
  const masterKey = sodium.sodium_malloc(32)
                           ^

Error: failed to create a n-api buffer
    at deriveMasterKeyFromRootKey (/Users/andrewchou/GitHub/digidem/comapeo-desktop/node_modules/@mapeo/crypto/lib/key-utils.js:43:28)
    at new KeyManager (/Users/andrewchou/GitHub/digidem/comapeo-desktop/node_modules/@mapeo/crypto/key-manager.js:41:23)
    at new MapeoManager (file:///Users/andrewchou/GitHub/digidem/comapeo-desktop/node_modules/@mapeo/core/src/mapeo-manager.js:121:24)
    at initializeCore (file:///Users/andrewchou/GitHub/digidem/comapeo-desktop/.vite/build/service/core.js:169:20)
    at file:///Users/andrewchou/GitHub/digidem/comapeo-desktop/.vite/build/service/core.js:75:40
    at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:316:24)
    at async node:electron/js2c/utility_init:2:17148
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:138:5)

Node.js v20.14.0

@mapeo/core uses sodium-universal under the hood. Seems related to sodium-friends/sodium-native#185. Haven't tried the suggested solutions there yet.

Replacing sodium-native with sodium-javascript via sodium-universal leads to a different issue (missing method due to incomplete implementation):

/Users/andrewchou/GitHub/digidem/comapeo-desktop/node_modules/@mapeo/crypto/lib/key-utils.js:45
  sodium.crypto_pwhash(
         ^

TypeError: sodium.crypto_pwhash is not a function

Edit device name

• User has gone through onboarding and has named their device
• User wishes to edit their device name
• User goes to Settings - Project Settings - Device Name
• Important : the following might be different because it's on desktop. Follow the visuals as : https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1567-547&mode=design&t=5vfTa0D7asyKjZKc-0

1

Todo

• Display Your Device Name
• Create edit button using pen icon at the top right

2

Todo

• When pen icon clicked, change to checkmark icon
• Display text box with device name
• Display max characters /60
• Note from Sabella : If user taps edit, show save button top right, Edit label and field. If a user makes changes to the name field but doesn’t tap Save we are going to show them a dialog box

3

Todo

• Display pop-up if user didn't click on Save and clicked elswhere
• Create Continue editing button
• Create Discard changes button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1200-69&mode=design&t=xfOwkkUA7kBhB7vK-0

Copydeck

https://docs.google.com/spreadsheets/d/1-ToQImFcHK6f0TpPJgpDIJf92kD1pIq8Cz6uH9meoVM/edit#gid=1868132643

Your team

• User was on Settings/Project Settings and clicked on Your team
• User is on a project and can see the project and available devices, leave project
• If user tries leave project if they are the only coordinator ( if clicked - pop up warning)
• User clicks on **Invite **

1

Todo

• Display screen as designed
• Create a Invite Device button
• Display text Coordinators
• Display text Coordinators can invite devices, edit and delete data, and manage project details.
• Display users own device
• Create a Leave Project button
• Display text Participants
• Display text Participants can take and share observations. They cannot manage users or project details.
• When no participants on project, display text No Participants have been added to this project

2

Todo

• Display Select Device to Invite as header
• Display text Not seeing a device? Make sure both devices are on the same wifi network. Make sure both devices are on the same version of Mapeo
• Display available devices by their Device Name
• Disregad Learn More button
• Create a Cancel button

3

Todo

• Display Select a Role as header
• Display text You are selecting a role for this device:
• Create a Participant button
• Display text As a Participant this device can take and share observations. They cannot manage users or project details.
• Create a Coordinator button
• Display text As a Coordinator this device can invite users, and manage project details.

4

Todo

• Display Review Invitation as header
• Display text You are inviting:
• Create a Coordinator button
• Create a Send Invite button

5

Todo

• Display text Waiting for device to accept invite
• Display time invite was sent
• Create a Cancel Invite button

Sabella - 👾 Dev team, this state should reflect the user waiting for someone to accept invite. So sit for 3 to 5 secs?

6

Todo

• Display text Invite Accepted

• Display device details

• Create a Add Another Device button

• If clicked Add Another Device button , go back to # 2

• Create a Close button

• When device is invited, display device name under Particpant or Coordinator

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1247-153&mode=design&t=pTdIgujzMShkwaNL-0

Copydeck

https://docs.google.com/spreadsheets/d/1l4_ImeOzXbnqsCG4BGxdH0elXFdm73e3RL_ME75wWT0/edit#gid=980984343

To better inform us of components that we'd want to implement as part of a potentially shared component library, we should start documenting what we need. This is also helpful for us in the future in the case that we want to use a different library or approach for implementing these.

• button
• text (typography)

Settings

• Integrate a Settings button on the main menu
• Organize the menu

1 Settings button

Todo

• Display the Settings button as designed

2 Settings

Todo

• Display the menu as designed for Settings
• Create a Create or Join Project button
• Display Create a new project or join existing one under Create or Join Project button
• Create a Project Settings button
• Display Categories, Config, Icons under Project Settings button
• Create a App Settings button
• Display Language, Security, Coordinates under App Settings button
• Create a Experimental Feature button
• Create a About CoMapeo button
• Display LVersion and build number under About CoMapeo button

3 Project Settings

Todo

• Display the menu as designed
• Create a Device Name button
• Create a Configuration button
• Create a Your Team button

4 App Settings

Todo

• Display the menu as designed
• Create a Language button
• Create a Coordinate System button
• Create a Map Management button
• Create a Security button
• Create a Experiments button

5 Map Management

Todo

• Display the menu as designed
• Create a Directional arrow button
• Create a Background maps button
• Create a Data layers button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1567-547&mode=design&t=pTdIgujzMShkwaNL-0

Invited Devices

• User was on Project Settings and clicked on Your team
• User is on a project and can see the project and available devices, leave project
• User cannot leave project if they are the only coordinator
• User has invited at least one device
• User cannot change the role of the invited devices

Todo

• List the device in chronological order, devices are not clickable

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1068-4024&mode=design&t=lw81UhsBQKXEHyHD-0

Create a shared text component that follows the design patterns of CoMapeo Mobile..

To Do

• Create Text component in sharedComponents folder
• Accepts styles but has a default styling to be confirmed with Aldo
• Uses styled() for style overrides

Props

type TextProp = {
     // check if it is a MessageDescriptor. If it is a message descriptor translate it using [formatMessage](https://formatjs.io/docs/react-intl/api#formatmessage)
     children : React.ReactNode || MessageDescriptor //https://formatjs.io/docs/react-intl/components#message-descriptor
     style: React.CSSProperties
}

Sync flow / success

• User has created or joined a project
• User tries to sync
• Use design guidelines for Desktop https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1247-153&mode=design&t=CcOJrUpAzxWQeujR-0

1 Pre-sync / No devices clicked on Sync

Todo

• Display the menu as designed
• Display Project name
• Display Your device name is XXXX
• If devices are nearby on local wifi, display XXXX Devices nearby/connected
• If no user has clicked on Sync, display No devices are syncing
• Create a Sync button

2 Pre-sync/ Devices clicked on Sync

Todo

• If a user/users clicked on Sync, display XXXX Devices Waiting to Sync with you

3 Syncing

Todo

• Display Syncing with XXXX Devices
• Adjust XXXX Devices nearby/connected if more devices joined the local wifi
• Create progress bar as designed, display Syncing and percentage
• Create a Stop Sync button

4 Syncing done

Todo

• Display Up to Date! No data to Sync
• Create a You’re all caught up! button
• If You’re all caught up! button is clicked, add glowing color red

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1068-4024&mode=design&t=lw81UhsBQKXEHyHD-0

Copydeck

https://docs.google.com/spreadsheets/d/1Oi3cgEEE-XxQJ11JSwOJRjvUBlgmNSMxvV0XHrSJoG0/edit#gid=199798000

Join Project

• User was in Settings./Your Team
• User clicked on Join a project

Todo

• Display page
• Display text title How to join a project
• Display text explaining how to join a project, copy tbd, for now add To join a project find a Coordinator of the project you wish to join. Tell them your device name and the Coordinator will send you an invite.
• Create Close button

Design

https://docs.google.com/spreadsheets/d/1kpoU-mr-fJyxbAxERqrhC2IyRd3T64YEs8fUDzbAFQY/edit#gid=583501046

Copydeck

https://docs.google.com/spreadsheets/d/1kpoU-mr-fJyxbAxERqrhC2IyRd3T64YEs8fUDzbAFQY/edit#gid=583501046

At the time of writing, Electron 31.1.0 is available. I was going to do this work when the v31 line was initially released, but wanted to wait on better-sqlite3 to publish a release that included compatible prebuilds. Starting from v11.1.0, better-sqlite3 now includes the compatible prebuilds, which makes this work more reasonable to do.

Upgrading should (hopefully) not be problematic in terms of existing app code. Better to do this sooner rather than later, when there's more app code that's reliant on Electron APIs.

To do

• eslint
• prettier
• husky pre-commit step
• [ ]

Leave Project/ Only Coordinator on project

• User has joined a project or has created a project, and wishes to leave it
• User is on the Your Team screen and clicks on Leave Project
• User is a Coordinator and the only one on the project
• See also #6

Todo

• Display copy as designed
• Create Go back button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1197-2021&mode=design&t=QtmXnVzzeLu46JPp-0

Copydeck

https://docs.google.com/spreadsheets/d/1QXPIdnOFIRAk41hfnGBMw1zEafD8Vp1ZwqDm4XiUR3g/edit#gid=1956858863

On mobile, we use Expo's SecureStore API to handle storage of the rootkey that's passed to core. We need something similar for desktop, where we securely store the key on a device level. The key is sensitive and therefore it does not seem appropriate to store it via electron-store (see note in docs).

Seems like safeStorage is the technically sound option? Minor concern is that it requires some user-intervention, which has UX consequences (at least on macOS, where it prompts you to enter your root password in order to let the app access the keychain).

Open to other options and thoughts. Haven't explored the ecosystem too much so maybe there's something that's appropriate that I missed.

First screen at launch

• User launches CoMapeo for the first time
• User is invited to Get Started

Todo

• Display onboarding screen with logo
• Create button Get Started button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1069-4606&mode=design&t=8p1fA5Pu7n24D7E5-0

Copydeck

https://docs.google.com/spreadsheets/d/18x135fNGqwryXcBoJGvtNSJJMHuPB48Vp0o1l16UyzY/edit?usp=sharing

• Install the core Material UI library and its dependencies.
• Integrate Material UI into the Project
• Make sure css baseline, fonts, and maybe icons are maybe working (font should be Rubik)
• Set Up Theme Provider
• Create a custom theme using Material UI's theme creation utilities.
  • color palettes
  • font size. e.g. ideally we specify a root size of 16px and then have have more semantic font size theme names like body, title, descriptions, etc that are relatively sized to that root value
  • spacing. similar to the font size, ideally have more semantic naming that map to either specific values or uses relative sizing (idk what the best approach is, probably the former for now)
  • https://www.notion.so/digidem/091e537955f7482f883962b4df8fb84b?v=d6158bd386064246892bae58398896ab
• Wrap the application with the ThemeProvider to apply the custom theme globally.

Leave Project

• User has joined a project and wishes to leave it
• User is on the Your Team screen and clicks on Leave Project
• If user is a Coordinator, and they are more than 1 coordinator in the project, follow the flow below
• If user is a Coordinator, and they are the only Coordinator go to 5

1

Use this design but edit content to match mobile

ToDo

• Display Leave project
• Display This will remove all Project Name data from your device
• Add mandatory checkbox next to I understand I will be deleting all data from Project Name from my device
• User cannot leave project is box is unchecked
• Create Leave Project button
• Create Cancel button

2 Error state

Todo

• If user tries to click on Leave project without checking the box, display error message

3 Leaving project progress

• Display progress bar as designed

4 Leaving project success

• Display You have left Project Catapult
• Create Close button

5 Leaving project/ 1 coordinator

• Display copy as designed
• Create Go back button

Design

https://www.figma.com/file/uzynHXR0xgJu19lsCoJyXN/%F0%9F%90%9A-Shell-App?type=design&node-id=1099-856&mode=design&t=ypas7TLUlTe7pRjw-0

Copydeck

https://docs.google.com/spreadsheets/d/1QXPIdnOFIRAk41hfnGBMw1zEafD8Vp1ZwqDm4XiUR3g/edit#gid=588765348