cobuy

🌱 📦 🍲 👪 Helping people buy good food at good prices, together.

Table of Contents

• Setup
• How our stack works
• Stack
• Folder Structure
• Available Scripts
  • npm start
  • npm run dev
  • npm test
  • npm run lint
  • npm run db
• Developer Notes
• License

Setup

Before we start, please

• install node@8 and npm@5
• install Git LFS
• install and set up Postgres for your system
• create a database in Postgres named cobuy_development (i.e. using a command like CREATE DATABASE cobuy_development; in psql)

git lfs install
git clone git@github.com:root-systems/cobuy
cd cobuy
npm run burnthemall # TODO npm install
# see 'How to get private development config' section below
npm run db migrate:latest
npm run db seed:run
npm run dev

System Dependencies

• Postgres
• git-lfs

How our stack works

Technical breakdown and references for/as examples

• Cobuy uses dogstack
• React and JSX for DOM stuff, as per, but also Hyperscript as an alternative to JSX
• Recompose in our React components for purity
  • Files: app/components/Navigation.js
  • PRs: https://github.com/root-systems/cobuy/pull/100/files
• Fela to manage styles
  • Files: <any dumb component and its style file>
• Material-UI for ready-styled components
  • Files: <any component that has buttons or text fields or sliders>
• React-intl to manage internationalization
  • Files: app/locales/en.json, <any component with text>
  • #80
• Storybook for developing and testing our dumb components easily
  • Files: .storybook/config.js, agents/stories/index.js, agents/stories/Profile.js
  • PRs: https://github.com/root-systems/cobuy/pull/51/files
• Redux for state management, as per
• Redux-fp for 'updaters' instead of 'reducers'
  • Files: */updaters/*
  • PRs: https://github.com/root-systems/cobuy/pull/103/files
• Redux-observable for managing async operations
  • Files: ordering/epic.js,
  • PRs: https://github.com/root-systems/cobuy/pull/103/files
• Redux-form to connect React forms to state
  • Files: agents/components/SignIn.js
  • PRs: https://github.com/root-systems/cobuy/pull/59/files
• Reselect for our getters
  • Files: */getters/*
  • PRs: https://github.com/root-systems/cobuy/pull/104/files
• Ramda as our general utility library with a strongly functional flavour
  • Files: <almost any>
• Feathers for our backend API layer
  • PRs: #116
• Feathers-reactive
• Feathers-action-react
• Feathers-action to provide CRUD actions out of the box
  • Files: */dux/*, */services/*, */containers/*, server.js,
  • PRs: #116
• Knex for interfacing with DB
  • Files: db/migrations/*
  • PRs: https://github.com/root-systems/cobuy/pull/116/files
• Dogstack-agents to manage users and credentials
  • Files: agents/containers/Register.js
  • PRs: https://github.com/root-systems/cobuy/pull/59/files

Basic relationships between things (very roughly and probably slightly incorrectly)

• Dumb components
  • components && style files
  • components && their local state
• Higher-order components (HOC) or containers
  • (container && getters && props && actions) && dumb component/s
• Dataflow within the client
  • from state to components
    • state -> getters -> HOC components (containers) -> dumb components
  • from components to state
    • dumb components -> HOC components (containers) -> actions -> updaters && epics -> state
  • from components to state with redux-form
    • dumb components -> redux-form -> redux-form state
• Dataflow between client and server
  • actions -> services && hooks -> db
  • services && hooks && db tables

Also see the Captain's Log for more epistolary notes

Stack

dogstack! 🐶 🐶 🐶

Folder Structure

We're following the dogstack folder structure convention.

• root
  • actions.js (combines all actions)
  • client.js
  • epic.js (combines all epics)
  • layout.js
  • package.json
  • root.js
  • routes.js
  • server.js
  • store.js (combines top-level epic and updater)
  • style.js
  • updater.js (combines all updaters)
  • topic (e.g. agents)
    • containers
    • components
    • helpers
    • getters
    • services
    • dux
    • styles
    • stories
    • util

Available Scripts

npm start

Starts production server

npm start

npm run dev

Starts development server

npm run dev

npm run storybook

Starts storybook server

npm run storybook

npm test

Runs ava tests

Can optionally take a glob

npm test -- './todos/**/*.test.js'

Default glob is ./**/*.test.js ignoring node_modules

npm run lint

Checks for standard style

Can optionally take a glob

npm run lint -- './todos/**/*.js'

default glob is ./**/*.js ignoring node_modules

npm run db

Runs knex command, with any arguments.

npm run db migrate:latest

npm run db seed:run

Developer Notes

Anything that a developer working on Cobuy should know about.

TODO organize all the miscy mushy magic

Postgres DEV setup

Use a ~/.pgpass file to automate your passwords!

echo "localhost:5432:*:postgres:password" > ~/.pgpass
chmod 600 ~/.pgpass

Create your database with:

createdb cobuy_development -h localhost -U postgres

Drop your database with:

dropdb cobuy_development -h localhost -U postgres

Connect to your database with:

psql -h localhost -U postgres -d cobuy_development

How to get private development config

Our development config is stored in a private repository:

cd ../
git clone git@github.com:Enspiral-Pods-Swarm/cobuy-config
cp cobuy-config/*.js cobuy/config

After deploy: migrate on heroku!

heroku run npm run db migrate:latest --app=cobuy

JSON schema

All models must have an assoicated JSON schema. See #118 for more info.

We're using json-schema-faker to fake data for tests and storybook.

How to storybook

So you want to tell a story about dumb React components, ey?

Start storybook with npm run storybook

The configuration for storybook lives in .storybook/.

The stories are in ${topic}/stories/index.js. The dumb components are in ${topic}/components/${name}.js

If you add a "story", please add your topic story to .storybook/config.js

Check out app/stories/index.js for example stories, which you can copy into a new topic.

NOTE: At the moment, hot-reload does not work when changing messages in app/locales/*.json.

Numbers

All numbers should be represented as strings and manipulated with bigmath.

Spelling in the code

Developers should be using British spelling in the codebase

Assets

All assets (binary files) should be checked in using Git LFS:

git lfs add <file>

They must also be manually added to our production OpenStack Object storage cobuy-assets container.

This can be found at: https://dashboard.cloud.catalyst.net.nz/project/containers/container/cobuy-assets

Ensure the name of the file is the same locally and remotely.

License

AGPL-3.0

Emoji artwork is provided by EmojiOne and is licensed under CC-BY 4.0