Table of Contents
- OGB Technical Specification
- OGB Modules
- Modules
- OGB Template Module
- OGB Body Balance Module (template data)
- Examples
- Template 1 Stakeholder driven
- Template 2 Max body size eg 60
- Template 3 Split between groups max body size 100
- OGB Signup Module
- OGB Invitation Module
- OGB User Management Module
- OGB Flagging Module
- OGB Sortition Module
- OGB Proposal Module
- OGB ActivityPub Tagging and Filtering
- OGB Voting
- OGB Filter Module
- Security and Open Data
- Privacy
- APIs
- NFR (Non Functional Requirements)
This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.
This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.
N.B. STILL A WORKING DOCUMENT - BEING REFINED
#OGB is basically a wiki with plugins and workflow toolkit
OGB Technical Specification
OGB Modules
Why choose to build v1.0 of OGB using XWiki
We chose XWiki as it is a well designed fully open source project that has already implemented many of the key requirements for OGB for example share document creation for our OGB proposals (Wiki Pages). It also has a well constructed plugin architecture so it can be easily enhanced without the need to fork the base project. Many of the plugins will be used as part of the OGB project.
Implementation
All the functionality will be implemented as standalone XWiki Module/Plugins that can provide useful functionality to the XWiki user community when used outside of OGB.
Deliverables
- OGB API specification for v1.0
- A build system that fully builds a working OGB from source code
- A simple to install prebuilt set of container images than can be deployed and run in minutes on popular personal and cloud platforms
- An OGB developer community running on the soon to be federated http://unite.openworlds.info
Modules
OGB Template Module
For use when starting a new OGB (Open Governance Body).
Use the existing XWiki template system to build a set of pages which cannot be accessed by non-developers. No access from the OGB users, except to clone.
Including a group that checks if some is a stakeholder or affiliate.
OGB Body Balance Module (template data)
Set the percentages of the top level members.types that are sorted into go into the body. This is run once when a new OGB is created using the template module.
Examples
Template 1 Stakeholder driven
All stakeholders are added to the body
An equal number of users are sortated
An equal number of affiliates are sortated or selected if less that the number of stakeholders
Template 2 Max body size eg 60
Fill the body by sortating 20 from each group. If the are less than 20 in a group select all
Template 3 Split between groups max body size 100
We have 100 stakeholders and users and 10 affiliates with a 10%,80%,10% split. Leads to 10 sortated stakeholders, 80 sortated users, and 10 affiliates.
The chosen template body data is then used by the sortation API.
Set ActPub tagging to display on each section sidebar
Use built in Templating of Xwiki to implement; filling any gaps using additional scrum process during testing
OGB Signup Module
Login if exsiting user on the instance
- Create new account as 'Member' (everyone):
- may decide to only observe or take part (untick the box "take role")
- create a personal wiki page with their activiypub stream; to do with what they want
- Upgrade to 'Stakeholder Member':
- fill in questionnaire body (template)
- a tagged activity pub message will get posted to the approval group
- group members can each submit 'approve' or 'disapprove' (this is useing the vote modual, likly with a passive time in/out)
- Upgrade to 'Affiliate Member':
- Fill in questionnaire body (template)
- a tagged activity pubmessage will get posted to the approval group
- group members then each submit 'approve' or 'disapprove' (this is useing the vote modual, likly with a passive time in/out)
OGB Invitation Module
Facilitating how members can invite new people, such as:
- Send email
- SMS
- QR codes
- Print Posters
- Signup URL
- AP event
Thesse will all work for the groups, then it would be a AP event
OGB User Management Module
All actions within an OGB instance related to actions taken on users are handled by the creation, editing and control of wiki pages. We therefore harness the built-in functionality of XWiki to perform such things as:
- member individuals
- member groups
- permissions or members/groups to edit and lock pages
- Create groups
- Join groups
- Leave groups
- Admin of groups
- Freeze/lock pages (make uneditable)
OGB Flagging Module
The intention here is to raise a notice upon something that should be looked at.
Everything in the system can be flagged - wiki pages (users via their personal wiki page), ActPub messages, etc.
There are thresholds (defined by a given template) such that a single flag might be pushed to a low-level activity stream, whereas multiple flags in e.g. a given time period may be pushed to a higher-level stream (more likely to be noticed by multiple parties).
Notifications are published by creating ActPub alerts and API actions.
OGB Sortition Module
- Determines who gets placed in a given 'Body'
- Runs every 10 mins
- Looks for any space in body
- Uses the ratios of sortition into 'Body Member' (1/3 1/3 1/3) from template model
- candidate for each pool are selected randomly from the candidates (who are taking part)
- Updates the new members rolls
- Posts to ActivityPub and alerts via email
- Streams are best kept to a minimum. The default shall be one per body/group, and one per user
- Second sortition runs to pick 'Voices' of the 'Body'
- 3 to 5 (template-defined) are picked and sortated as voices (see above)
- Members may be regularly refreshed based on a timeline defined in the initial template, e.g.
- Once every year, all body members are refreshed
- Once every 6 months half the body is refreshed
OGB Proposal Module
This is the most important piece of development for OGB.
Proposed life cycle:
1. Draft Stage
Create and name a draft
Accept voting default or change to one that is in the template
Anyone in the creating group can write and amend the proposal
Anyone in the OGB can comment
The proposal is implemented as a XWiki page
Any supported media can be added
All changes are announced using Activity Pub
2. Voting
The person who created the proposal can put it to the vote
Additions are frozen during the voting
Comments are allowed
Anyone in the creating group can vote
3. Results
When the voting time closes the design is announced and the proposal is shown on the passed or failed pages of group/body
4. Escalate
The person who created the proposal can escalate it
Clone the proposal and send to a different entity
Amendment can be made and the re-voted on
Back to step 1
n.b. A better term is required for this action - denoting giving weight/force to a proposal.
Implementation
Use XWiki pages for proposals, with comments and Access Control List (ACL) for the entity members.
Use the Voting Module to vote.
OGB ActivityPub Tagging and Filtering
As mentioned earlier, minimising the number of ActPub streams keeps things simpler to maintain.
As such, there may be a single stream for a given group. WIthin that stream, #tags will be used to demarkate flows within the stream.
We will implement filters on these tagged flows to display relevant content on a given page - further narrowed by the group and template.
- Goals support new users
- Flagging challenging content
- Showing the write notification in the appropriate section
- Giving feedback on proposals
OGB Voting
- 3 options
- can vote on any "proposal"
- if it goes through, then one of the admins/mod takes the action
- it auto announces via ActPub
OGB Filter Module
Facilitate how hashtags and/or categories from ActivityPub messages are processed by various parts of the OGB system.
Various separate designations within OGB should be able to filter specific messages/posts. This module provides the ability for other modules to achieve this.
- Members
- Stakeholders
- Affiliates
- Body
- Voice
- Groups
- Admin
- Group Members
- Roles
Security and Open Data
We will use Oath v2 to implement the login system with option of using 2FA for uses and mandatory use for admins.
Account creation and login on new machine will require a capture to block access by bots
Full write once audit log of all operation (excluding personal data)
Fully compliant with GDPR in both technology and processes.
End user can download all of their data
Being open improves our security. All public creations, updates, comments, and tagging is automatically published via activity pub. User can opt to have daily summaries
of filtered Activity Pub messages APP sent to them via email. This makes a very open system. As all public changes can be alerted via AP showing who made the change and the AP message can be clicked on to see the item or the person's personal wiki page.
Data classified as personal is never shared with other users.
No data is sold.
During development a full data audit will be carried out which will be published showing exactly what data is collected and what it is used for.
The T&C will make it clear that any content published will be classified as a CC licence (set within a given template) and be freely accessible on the OGB system.
We encourage the global community to use the #4opens data for research projects to help improve OGB coding and local democracy in general.
Privacy
To run a private implementation of OGB, it must be run on an intranet, firewalled from public access. Use must be onsite or via a VPN connection.
APIs
All API will be REST (REpresentational State Transfer).
See Wikipedia: https://en.wikipedia.org/wiki/Representational_state_transfer
The following table shows how HTTP methods are intended to be used in HTTP APIs, including RESTful ones.
HTTP Method Description
---------------------------------------------------------------------------------
GET Get a representation of the target resource’s state
POST Let the target resource process the representation enclosed in the
request
PUT Create or replace the state of the target resource with the state
defined by the representation enclosed in the request
DELETE Delete the target resource’s state
The APIs will be versioned and open so any implementation of these APIs using any computer language will deliver the same or additional OGM features.
The details of the v0.1 API will be designed by the team during the project kickoff. This will evolve through issues and learnings during the build phase and when we launch we will publish the v1.0 API specification all updates to v1.x will be non-breaking and will be backwards compatible with all v1.x versions. Version v2.0 will be planned and built after running the project for at least 1 year with the experience of many active instances and users.
Each module will have back-end API shims/adapters where it talks to specific functionality within XWiki. These can be replaced to allow other systems to be used to implement OGB. For example OGB could be implemented using other wiki’s by replacing the shims.
Database Schema
To be designed during project kickoff
NFR (Non Functional Requirements)
Development
GIT Version control
GIT Flow with feature branches
Code review at check in
All logic and algorithms must be documented
High level of automated testing coverage
Developers are able to run their own development instance
Release notes
Change sign off for production
Zero downtime updates (using green blue pattern)
Quality Control
Dedicated QA staff
Automated and manual testing
Prerelease testing
Regression testing
Active monitoring and issue alerting
Dashboard to clearly see the current performance
Performance
High performance that scales up and down
Paged data access. The UI only loads data needed to show on the current page
Scaling based on partner and user usage load
Processing times for imports and exports
Reliability
2 physical live (active/active) locations for all production infrastructure and data storage
Security Encryption of all data during transmission
Encryption of all data at rest (files and databases)
Use a key management system so the keys are not exposed to ops and devs
Password requirements - length, special characters, expiry, recycling policies, 2FA Login / Access levels
User session / Inactivity management - Durations, actions
Audit table of all user driver changes so it is clear who did what
Capacity
High transactions per second
Storage - how much data does the system need to store
Year-on-year growth requirements
Integrity
Bad data trapping - data imports, flag and continue, stop the import policies
Filtering test data from production
Localization Support
Translation facilities
Directory based e.g. /pt /it
Disaster planning
Recovery plan for systems and staff
Backup of code and data
Frequency Process of restoring data and backups
Definitions
The definitions and naming that we use in this document are not actually the final terminology. They will be formalised during the implementation.
Team Members
Tom, Hamish, Michael, one programmer yet to be employed