powerhouse-inc/switchboard

Collect initial requirements

valiafetisov opened this issue · 6 comments

valiafetisov commented

Goal

List of short and long-term requirements

Context

In order to come up with the proper technical proposal, we need to summarise list of technical requirements. Currently, there are several of them:

  • Technical requirements defined by Wouter
  • Requirements that can be derived from the document model in #1
  • Technical requirements that can be potentially derived from the product/problem itself

This issue then should become a central place for collecting those requirements

Tasks

  • Collect all existing requirements
  • Derive clear/unclear requirements from the document model issue
  • Split into short- and long-term requirements
valiafetisov commented

Technical requirements defined by Wouter

  • Testing
    • Primitives/utilities unit testing, Database model testing, Input validation testing, Authorization logic testing, End-to-end, request/response flow testing
    • Happy path + edge cases testing
    • Database dependence
      • As much as we can reasonable do, testing should be independent of the database content
      • Usage of a demo database may need to be considered for the other cases
    • Generate a code coverage report and agree on a target level = recently enabled in the current code base
  • Modules
    • Create documentation for every module
    • Create a separate namespace for every module in the database
    • Shape the API so that user understands which module they're interacting with
  • API services / plugins that cover cross-cutting concerns
    • Authentication
    • Authorization
    • Error and performance logging (winston): should be able to toggle it, at least on a module level > to be plugged in to server logging infrastructure later
    • Rate limiting and API keys
      • Usage stats + performance data: need to know which queries are used, and how long they take
    • Input validation
    • History of the data records - using the document model
  • Release cycle, CI/CD
    • Solid support for database migrations (per module)
    • CI pipeline with automated unit and/or integration testing + test coverage reporting
  • Base functionality
    • Figure out the right way to apply polymorphism
    • Calculated data flow = this is currently under development - timescaledb
      • Needs a consistent caching mechanism
      • Should be easy to check that it updates correctly whenever the input data changes
    • User activity generator + gamification mechanics
valiafetisov commented

Requirements derived from the document model #1

Note: lines marked as "checked" means that we transferred those requirements to the following comment below.

  • Store history of every record (aka "document state revisions")
  • Store change requests (aka "document operations")
    • ? Structure change requests not as a generic CRUD, but as a high-level business-centric set of actions (not sure if that's an actual requirement, reading between the lines in this case)
    • Data that needs to be stored:
      • Name of the change (i.e.: endpoint?)
      • The object of named input parameters (i.e.: parsed request body?)
      • Reference to the document revision it produced
  • Implement UI to preview records with referenced records, attached files and history (aka documents) in the browser
  • Implement UI to execute possible operations over the document
  • Implement UI to dry-run operations over the document (i.e.: execute and see the result without making requests to the backend, frontend-side)
  • Allow offline/sharable documents (documents that doesn't end up in the database, but can benefit from the same UI and data structure)
    • Prepare set of operations on the frontend (committing those operations to the backend is optional)
    • Download state together with the set of committed and uncommitted operations as a file (or maybe share via protected/encrypted url)
    • ? Store database models (aka "document processors") as a standalone, 0-dependency code (in order to be able to provide it for the download) – tricky due to migrations, dependencies, etc, as explained in #1
    • ? Add new models, operation types and state structures by editing the model code – this requirement is still unclear
valiafetisov commented

Technical requirements that can be potentially derived from the product/problem itself

From my perspective, this project would vastly benefit from a declarative style of models/input validators/auth rules, etc, since we don't want to reimplement this complex logic for every new model. So the requirement that I would enforce on top is the use of ORM that define models based on a declarative config of our own structure (that we can extend in the future)

Other requirements

  • Read-only database replica for analysts to run pure SQL queries
  • Simple web interface for analysts / Existing standalone interface for read-only SQL exploration
  • Easy integration with services like observablehq
valiafetisov commented

Split into short- and long-term requirements

Short-term requirements

  • Setup a project with a linter and a prettier
  • Setup ORM, declarative module structure
  • Setup database migrations
  • Setup something like tsdoc (can be enforced via a linter rule)
  • Setup tests for operations, models, database integration. Set high code coverage threshold early on
  • Add CI steps to enforce tests, coverage, correct build outcome
  • Add input validator (+possibly enforce its use via the config structure)
  • Setup API playground (+possibly make database/code comments visible in the playground)
  • Setup advanced logging library like winston, enforce correct usage (via a readme guide, linter settings)
  • Implement authorization and authentication as a plugin/middleware
  • Implement UI to login, create users and their API keys
  • Add CD steps to build and deploy staging on merge to main
  • Store history of every record
  • Store change requests (endpoint path, parsed request body, reference to the record version it produced)
  • Store attached files (as base64 or upload them somewhere)

Long-term

  • Add CI steps to generate and publish docs
  • Add CD steps to build and deploy production on github release tag
  • Add rate limits
  • Collect usage stats
  • Setup logging infrastructure to collect and structure logs between instances
  • Implement UI to preview records with referenced records, attached files and the history
  • Implement UI to execute possible operations over the document
  • Implement UI to dry-run operations over the document
  • Allow offline/sharable documents
BracketJohn commented
  • can you make the document model bullets to checkboxes and then check everything that's already inside this short / long term requirement list?
  • other than that: I don't quite understand where the collaborative nature of outside-contributors via the "module" approach comes in here - can you make this clearer / say something about this?
valiafetisov commented

can you make the document model bullets to checkboxes and then check everything that's already inside this short / long term requirement list?

Did that. Basically all requirements derived from the document model were used in some way in the Short+long-term summary.

I don't quite understand where the collaborative nature of outside-contributors via the "module" approach comes in here - can you make this clearer / say something about this?

Since it's been declared undesirable to store model itself in the database, the only requirements for outside-contribution are good documentation + clear module structure (ie easy extensibility), the rest will be done via normal github PR flow.