├── CODE-OF-CONDUCT.md ├── LICENSE.md ├── OC-System.svg └── README.md /CODE-OF-CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | OpenCompany is an inclusive project, all are welcome. 4 | 5 | As users, contributors, and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. 6 | 7 | We are committed to making participation a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. 8 | 9 | Project maintainers have the right to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team. 10 | 11 | Please respect each other. Do not dismiss, abuse, harass, attack, insult or discriminate against others. This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. 12 | 13 | If you feel this code has been violated, please report the incident by contacting Stuart Levinson via [email](mailto:stuart@opencompany.com). We will work with you to resolve the issue promptly. 14 | 15 | This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.1.0, available at: [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/) -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | ## creative commons 2 | 3 | # Attribution-ShareAlike 4.0 International 4 | 5 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. 6 | 7 | ### Using Creative Commons Public Licenses 8 | 9 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. 10 | 11 | * __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). 12 | 13 | * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). 14 | 15 | ## Creative Commons Attribution-ShareAlike 4.0 International Public License 16 | 17 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 18 | 19 | ### Section 1 – Definitions. 20 | 21 | a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 22 | 23 | b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 24 | 25 | c. __BY-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. 26 | 27 | d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 28 | 29 | e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 30 | 31 | f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 32 | 33 | g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. 34 | 35 | h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 36 | 37 | i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 38 | 39 | j. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. 40 | 41 | k. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 42 | 43 | l. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 44 | 45 | m. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 46 | 47 | ### Section 2 – Scope. 48 | 49 | a. ___License grant.___ 50 | 51 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 52 | 53 | A. reproduce and Share the Licensed Material, in whole or in part; and 54 | 55 | B. produce, reproduce, and Share Adapted Material. 56 | 57 | 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 58 | 59 | 3. __Term.__ The term of this Public License is specified in Section 6(a). 60 | 61 | 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 62 | 63 | 5. __Downstream recipients.__ 64 | 65 | A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 66 | 67 | B. __Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. 68 | 69 | C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 70 | 71 | 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 72 | 73 | b. ___Other rights.___ 74 | 75 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 76 | 77 | 2. Patent and trademark rights are not licensed under this Public License. 78 | 79 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 80 | 81 | ### Section 3 – License Conditions. 82 | 83 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 84 | 85 | a. ___Attribution.___ 86 | 87 | 1. If You Share the Licensed Material (including in modified form), You must: 88 | 89 | A. retain the following if it is supplied by the Licensor with the Licensed Material: 90 | 91 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 92 | 93 | ii. a copyright notice; 94 | 95 | iii. a notice that refers to this Public License; 96 | 97 | iv. a notice that refers to the disclaimer of warranties; 98 | 99 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 100 | 101 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 102 | 103 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 104 | 105 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 106 | 107 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 108 | 109 | b. ___ShareAlike.___ 110 | 111 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. 112 | 113 | 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. 114 | 115 | 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. 116 | 117 | 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. 118 | 119 | ### Section 4 – Sui Generis Database Rights. 120 | 121 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 122 | 123 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 124 | 125 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and 126 | 127 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 128 | 129 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 130 | 131 | ### Section 5 – Disclaimer of Warranties and Limitation of Liability. 132 | 133 | a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ 134 | 135 | b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ 136 | 137 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 138 | 139 | ### Section 6 – Term and Termination. 140 | 141 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 142 | 143 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 144 | 145 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 146 | 147 | 2. upon express reinstatement by the Licensor. 148 | 149 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 150 | 151 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 152 | 153 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 154 | 155 | ### Section 7 – Other Terms and Conditions. 156 | 157 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 158 | 159 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.t stated herein are separate from and independent of the terms and conditions of this Public License. 160 | 161 | ### Section 8 – Interpretation. 162 | 163 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 164 | 165 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 166 | 167 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 168 | 169 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 170 | 171 | ``` 172 | Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. 173 | 174 | Creative Commons may be contacted at creativecommons.org 175 | ``` -------------------------------------------------------------------------------- /OC-System.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 |

Storage
RethinkDB
[Not supported by viewer]

Auth
RethinkDB
[Not supported by viewer]
Slack
Slack
FileStack
FileStack
AWS SNS/SQS
AWS SNS/SQS
Email Service
Email Service

Change Service
<div><br></div>Change Service
API
API

Storage Service
[Not supported by viewer]
API
API

Interaction Service
[Not supported by viewer]
API
API
AWS SES
AWS SES
Google Sheets
Google Sheets
publish
publish
consume
consume
publish
publish
consume
consume

Proxy Service
<div><br></div>Proxy Service
API
API
Web UI
Web UI
HTTPS
WSS
[Not supported by viewer]
WSS
[Not supported by viewer]
SSO
SSO
AWS S3
AWS S3
AWS CloudFront
AWS CloudFront
consume
consume

Change
DynamoDB
[Not supported by viewer]

Auth Service
<div><br></div>Auth Service
API
API

Bot Service
[Not supported by viewer]
API
API
Search
Service
[Not supported by viewer]
API
API
consume
consume

Elastic Search
<br><div>Elastic Search</div> -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Developer Onboarding 2 | 3 | > Transparency is the currency of trust, the open sharing of information among parties involved. Often, a decline in transparency is the first indicator of trouble. As transparency declines, trust declines. 4 | 5 | > -- [Christopher S. Penn](http://www.christopherspenn.com/) 6 | 7 | Companies struggle to keep everyone on the same page. People are hyper-connected in the moment but still don't know what's happening across the company. Employees and investors, co-founders and execs, customers and community, they all want more transparency. The solution is surprisingly simple and effective - great company updates that build transparency and alignment. 8 | 9 | With that in mind we designed the [Carrot](https://carrot.io/) software-as-a-service application, powered by the open source [OpenCompany platform](https://github.com/open-company). The product design is based on three principles: 10 | 11 | 1. It has to be easy or no one will play. 12 | 2. The "big picture" should always be visible. 13 | 3. Alignment is valuable beyond the team, too. 14 | 15 | Carrot simplifies how key business information is shared with stakeholders to create alignment. When information about growth, finances, ownership and challenges is shared transparently, it inspires trust, new ideas and new levels of stakeholder engagement. Carrot makes it easy for founders to engage with employees and investors, creating alignment for everyone. 16 | 17 | [Carrot](https://carrot.io/) is GitHub for the rest of your company. 18 | 19 | Transparency expectations are changing. Organizations need to change as well if they are going to attract and retain savvy employees and investors. Just as open source changed the way we build software, transparency changes how we build successful companies with information that is open, interactive, and always accessible. Carrot turns transparency into a competitive advantage. 20 | 21 | To get started, head to: [Carrot](https://carrot.io/) 22 | 23 | Information for new OpenCompany platform developers: 24 | 25 | * [Technical Values](#technical-values) 26 | * [Technical Priorities](#technical-priorities) 27 | * [Process Priorities](#process-priorities) 28 | * [Architectural Priorities](#architectural-priorities) 29 | * [System Architecture](#system-architecture) 30 | * [Coding Guidelines](#coding-guidelines) 31 | * [Tools](#tools) 32 | * [Code of Conduct](#code-of-conduct) 33 | * [License](#license) 34 | 35 | 36 | ## Technical Values 37 | 38 | **KISS** - **K**eep **I**t **S**imple **S**tupid - Complexity is our enemy. We need to solve the complexity inherent in the problems we face using simple solutions, and avoid introducing complexity that isn't inherent. Solution complexity is rejected, rather than dealt with. We ask [5 whys](http://en.wikipedia.org/wiki/5_Whys) about complexity. What can be relaxed or changed to make the complexity go away? 39 | 40 | **YAGNI** - **Y**ou **A**in't **G**onna **N**eed **I**t - This is the answer to much introduced complexity. We force complexity upon ourselves by being so good at asking "But what if...?" Instead, we build for the problems we have today, not for the problems we think we might have someday. None of us are fortune tellers. We're mostly wrong. 41 | 42 | **No Punting** - No one owns an app, a system a section of code, or a problem. We don’t punt issues off to others just because we weren't involved in the inception. Everyone works on, and fixes everything. Not knowing how something works doesn't mean you don’t work on it or fix it, it means the opposite! We seek out every opportunity to work on things we don't know about (and we fill in any missing documentation as we learn). Everyone on the team is full-stack. No specialists. 43 | 44 | 45 | ## Technical Priorities 46 | 47 | 1. Simple & DRY with a single responsibility 48 | * **Simple** - see KISS and YAGNI above. 49 | * **DRY** - **D**on't **R**epeat **Y**ourself - there's no place for copy and paste. It inevitably bites you in the ass. 50 | * **Single Responsibility** - units of software do 1 thing well, and only 1 thing. This is fractal and applies to lines of code, functions, classes, services, systems, and apps. 51 | 2. Transparent & manageable - logs, analytics, error reporting, separation of config from code, and real-time adjustments are good 52 | 53 | By following these 2 top technical priorities, we get two important emergent properties: **robustness** and **scalability** 54 | 55 | Our full set of technical priorities, in order: 56 | 57 | 1. Simple & DRY with a single responsibility 58 | 2. Transparent & manageable 59 | 3. Secure 60 | 4. Consistent 61 | 5. Documented 62 | 6. Tested 63 | 64 | Developers are held accountable to these technical priorities. Code reviews are structured around these technical priorities. 65 | 66 | Living these priorities requires hard thinking about the technical problems we face. Code that works is not the goal. Code that works by embodying these priorities, and the appropriate trade-offs between them, is the goal. 67 | 68 | 69 | ## Process Priorities 70 | 71 | Production code gets tested. Tests run in [continuous integration (CI)](https://en.wikipedia.org/wiki/Continuous_integration). Not all code needs all kinds of tests (unit, integration, system, acceptance, ...). Pragmatism still rules and strict [test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development) is not important to us (we prefer our own acronym of TDD, thinking-driven development), but automated test development is a core skill of all our developers and test automation is a key consideration in code reviews. 72 | 73 | All services do their best to trap and report errors. Error handling and alerting is a key consideration in code reviews. 74 | 75 | Deployment is automated. It's not done until it ships with automated deployment. It ships as soon as possible. Risk is mitigated by shipping small changes incrementally. 76 | 77 | All developers write documentation. Documentation is part of code review: did the appropriate docs get created and updated for the addition/change? 78 | 79 | Documentation is well-organized. Even when good docs exist, if the person that needs them doesn't know where they are or that they exist, they do no good. 80 | 81 | Code is documented. Comments are good! It’s always critical to comment on why this code is doing what it's doing. It’s also important to comment on what the code is doing, when that's not completely obvious. 82 | 83 | 84 | ## Architectural Priorities 85 | 86 | We build services, not monoliths. Services compose in architecturally sound ways to deliver services to layers higher up the stack. 87 | 88 | Libraries are better than micro-frameworks, which are better than monolithic frameworks. 89 | 90 | Observers are better than Pub/Sub, which is better than Queued Data Pipelines, which are better than Synchronous Services. Observers and queues are more robust than synchronous services (e.g. HTTP) and should be preferred where appropriate. 91 | 92 | We use the right language for the job. We are a polyglot team. We prefer polyglot developers who have learned how to efficiently learn new things. 93 | 94 | The right language for the job is generally obvious due to a language feature or library implemented in the language that makes the job a much easier match for our [technical priorities](#technical-priorities). The job becomes much simpler, or more robust, or easier to test, etc. 95 | 96 | If the job is general purpose utility computing with no language feature or library advantages, we use [Clojure and ClojureScript](#tools) as our default. 97 | 98 | 99 | ## System Architecture 100 | 101 | OpenCompany uses a distributed microservices architecture. Many services provide access to themselves via HTTPS and/or 102 | WSS APIs. Others provide their services through the SQS queuing service. A key linchpin is JWToken authentication 103 | tokens which are used to provide cross-service authentication and user state. A typical use of the service is through 104 | the OpenCompany web client. 105 | 106 | ![System Diagram](https://cdn.rawgit.com/open-company/developer-onboarding/master/OC-System.svg) 107 | 108 | ### Quick Glossary 109 | 110 | [Auth RethinkDB](https://github.com/open-company/open-company-auth#technical-design) - RethinkDB data store of users 111 | 112 | [Auth Service](https://github.com/open-company/open-company-auth) - Authentication microservice, handles user authentication, Slack single sign-on, and JWToken generation (HTTPS) 113 | 114 | [AWS CloudFront](https://aws.amazon.com/cloudfront/) - Content delivery network 115 | 116 | [AWS S3](https://aws.amazon.com/s3/) - Simple Storage Service 117 | 118 | [AWS SES](https://aws.amazon.com/ses/) - Simple Email Service 119 | 120 | AWS SNS/SQS - [Simple Notification Service](https://aws.amazon.com/sns/) and [Simple Queuing Service](https://aws.amazon.com/sqs/) 121 | 122 | [Bot Service](https://github.com/open-company/open-company-bot) - Slack bot microservice, handles Slack integration other than single sign-on (HTTPS/SQS) 123 | 124 | [Change DynamoDB](https://github.com/open-company/open-company-change#technical-design) - DynamoDB store of change and see events 125 | 126 | [Change Service](https://github.com/open-company/open-company-change) - Change tracking microservice, handles read/unread state per user and async notifications of new content (WSS) 127 | 128 | [Notify Service](https://github.com/open-company/open-company-notify) - Service that handles general purpose notifications to users and notifications for mentions in comments and posts. 129 | 130 | [Reminder Service](https://github.com/open-company/open-company-reminder) - Service that supports scheduling reminders to users. 131 | 132 | [Email Service](https://github.com/open-company/open-company-email) - Microservice for outbound content and transactional emails (SQS) 133 | 134 | [FileStack](https://www.filestack.com/) - File upload as a service 135 | 136 | [Google Sheets](https://www.google.com/sheets/about/) - Spreadsheets in the Google cloud 137 | 138 | [Interaction Service](https://github.com/open-company/open-company-interaction) - Engagement microservice, handles user engagement with reactions and comments (HTTPS, WSS) 139 | 140 | [Proxy Service](https://github.com/open-company/open-company-proxy) - Charting microservice, handles extracting charts from Google Sheets (HTTPS) 141 | 142 | [Search Service](https://github.com/open-company/open-company-search) - Microservice for searching and indexing carrot data. (SQS and Elastic Search) 143 | 144 | [Slack Router](https://github.com/open-company/open-company-slack-router) - Microservice for receiving slack API events and publishing them to SNS. 145 | 146 | [Slack](https://api.slack.com/) - Company chat application 147 | 148 | [Storage Service](https://github.com/open-company/open-company-storage) - Persistence microservice, handles information data management and access control (HTTPS) 149 | 150 | [Storage RethinkDB](https://github.com/open-company/open-company-storage#technical-design) - RethinkDB data store of user content 151 | 152 | [Web UI](https://github.com/open-company/open-company-web) - ClojureScript/React mobile and desktop web client 153 | 154 | 155 | ## Coding Guidelines 156 | 157 | We're much more interested in ensuring code follows the values and priorities described above than that it follows any particular coding standard. Code formatting is just the small tip of a very large iceberg; poorly formatted code can be programmatically tidied, but poorly done thinking can't be programmatically rethought. That being said, here are some code guidelines we look for: 158 | 159 | * Do your best to conform to the coding style that's already there in the repository... That means we like it. 160 | * Use 2 soft spaces for indentation for white space irrelevant code/data. Use 4 soft spaces for white space relevant code/data. 161 | * Don't leave trailing spaces after lines. 162 | * Don't leave trailing new lines at the end of files. 163 | * We prefer `defn-` to `:^private` where its use is possible 164 | * Write comments. Comments are good. 165 | * Write tests. Tests are good. 166 | * Don't submit über pull requests, keep your changes focused and atomic. 167 | * Submit pull requests to the `mainline` branch of repos. 168 | * Have fun! 169 | 170 | ### Pull Request Process 171 | 172 | The purpose of the pull request process is to ensure code and product quality. The reviewer has 2 important responsibilities: code quality via code review, and product quality via QA of the change, ensuring both that the new functionality or fix works as expected and that other related parts of the product haven't regressed. 173 | 174 | 1. The creator of the pull request is responsible for adequately describing the change being made. The main components of the description are what changed, how it changed, and why it changed, and what steps were taken to fully QA the change. 175 | 1. The creator of the pull request marks them-self as the assignee, which signifies they are the primary submitter of the change and will be the one to respond to reviewer's question, comments and requests for changes. If at some point another developer becomes the primary contributor of the change, the assignee is changed. 176 | 1. At this point though, the PR is not yet ready for review, it may still be in progress. Once it is ready to be reviewed, the assignee adds the label "ready for review". In the unusual case that the assignee wants the PR reviewed by a specific developer, they can also assign that developer with the reviewer field. NB: This is not usually done and you need a good reason to want a specific reviewer. 177 | 1. At this point, any other developer that sees the PR should do the review, assigning themself with the reviewer field, removing the "ready for review" label, and labeling it with "reviewing". The reviewer reviews the code and performs QA, repeating the steps provided in the PR description *and* thinking critically about what additional QA steps may have been missed by the assignee. 178 | 1. Now the usual back and forth commences between the assignee and the reviewer consisting of questions, comments, ideas, requests, suggestions and changes. NB: Reviews are about the code, not about the people, as an assignee, try to remain objective and not take anything from the reviewer personally, and as a reviewer, be kind and stay focused on the code. 179 | 1. Once the code is in a place that both the assignee and reviewer are happy with it, it is the assignees responsibility to merge the PR and get the code deployed into production. Any special notes on deployment steps or dependencies should be included in the PR for the reviewer. 180 | 181 | ## Tools 182 | 183 | If the job is general purpose utility computing with no language feature or library advantages, we use Clojure and ClojureScript as our default. 184 | 185 | ### Clojure 186 | 187 | [Clojure](http://clojure.org/) is a Lisp that targets the [Java Virtual Machine (JVM)](https://en.wikipedia.org/wiki/Java_virtual_machine). 188 | 189 | Tutorials: 190 | 191 | * [Clojure From the Ground Up](https://aphyr.com/posts/301-clojure-from-the-ground-up-first-principles) 192 | * [Clojure for the Brave and True](http://www.braveclojure.com/) 193 | 194 | References: 195 | 196 | * [Clojure Distilled](https://yogthos.github.io/ClojureDistilled.html) 197 | * [Cheatsheet](http://jafingerhut.github.io/cheatsheet/grimoire/cheatsheet-tiptip-cdocs-summary.html) 198 | * [ClojureDocs](http://clojuredocs.org/) - a community-powered documentation and examples repository for Clojure 199 | * [Quickref for Clojure Core](http://clojuredocs.org/quickref) 200 | * [Clojure Quick Reference](http://faustus.webatu.com/clj-quick-ref.html) 201 | * [Clojure Codex](http://www.stuttaford.me/codex/) - curated links 202 | 203 | Libraries: 204 | 205 | * [A Directory of Clojure Libraries](http://clojure-doc.org/articles/ecosystem/libraries_directory.html) 206 | * [Clojure Libraries](https://clojure-libraries.appspot.com/) 207 | * [Luminus Useful Libraries for Clojure Web Development](http://www.luminusweb.net/docs/useful_libraries.md) 208 | * [The Clojure Toolbox](http://www.clojure-toolbox.com/) 209 | 210 | Other: 211 | 212 | * [Leiningen](http://leiningen.org/) - declarative dependency management and build tool (via plugins) 213 | * [Boot](https://github.com/boot-clj/boot) - functional build and dependency management tool 214 | * [Clojurians on Slack](http://clojurians.net/) 215 | * [Clojure email list](https://groups.google.com/d/forum/clojure) 216 | 217 | ### ClojureScript 218 | 219 | [ClojureScript](https://github.com/clojure/clojurescript) is a Clojure compiler that targets JavaScript to run Clojure in the browser (or on server-side JavaScript interpreters). 220 | 221 | Tutorials: 222 | 223 | * [ClojureScript Tutorial](http://www.niwi.be/cljs-workshop/) 224 | * [ClojureScript Unraveled](http://funcool.github.io/clojurescript-unraveled/) 225 | * [ClojureScript Koans](http://clojurescriptkoans.com/) 226 | 227 | Reference: 228 | 229 | * [ClojureScript Cheatsheet](http://cljs.info/cheatsheet/) 230 | * [ClojureScript Syntax in 15 minutes](https://github.com/shaunlebron/ClojureScript-Syntax-in-15-minutes) 231 | * [ClojureScript translations from JavaScript](http://kanaka.github.io/clojurescript/web/synonym.html) 232 | 233 | Other: 234 | 235 | * [CLJSFiddle](http://cljsfiddle.net/) - try your ClojureScript online 236 | * [ClojureScript email list](https://groups.google.com/d/forum/clojurescript) 237 | * [core.async](https://github.com/clojure/core.async) - library for async communication, often used in ClojureScript ([reference](https://clojure.github.io/core.async/)) 238 | 239 | ### Rum 240 | 241 | [Rum](https://github.com/tonsky/rum) is a ClojureScript interface to [React](http://facebook.github.io/react/). 242 | 243 | References: 244 | 245 | * [Rum wiki](https://github.com/tonsky/rum/wiki) 246 | 247 | Libraries: 248 | 249 | * [Derivatives](https://github.com/martinklepsch/derivatives) - library for deriving needed component state from state atom 250 | 251 | Other: 252 | 253 | * [Rum workshop video](https://www.youtube.com/watch?v=RqHnxkU9TZE) 254 | 255 | ### RethinkDB 256 | 257 | [RethinkDB](http://rethinkdb.com/) is an open-source, multi-modal (document, key/value, relational) database. 258 | 259 | Tutorials: 260 | 261 | * [Quick Start](http://rethinkdb.com/docs/quickstart/) 262 | * [Ten-minute Guide](http://rethinkdb.com/docs/guide/javascript/) 263 | 264 | Reference: 265 | 266 | * [Clojure API Reference](http://apa512.github.io/clj-rethinkdb/) 267 | 268 | Other: 269 | 270 | * [clj-rethinkdb](https://github.com/apa512/clj-rethinkdb) - a RethinkDB client for Clojure 271 | 272 | 273 | ### Elasticsearch 274 | 275 | Elasticsearch is an open-source, distributed, JSON-based search and analytics engine designed for horizontal scalability, maximum reliability, and easy management. 276 | 277 | References: 278 | 279 | * [Elastic Stack and Product Documentation](https://www.elastic.co/guide/) 280 | 281 | Libraries: 282 | 283 | * [http://clojureelasticsearch.info/](Elastich) - an Elasticsearch client for Clojure 284 | 285 | 286 | ## Code of Conduct 287 | 288 | Please note that this project is released with a [Contributor Code of Conduct](https://github.com/open-company/developer-onboarding/blob/master/CODE-OF-CONDUCT.md). By participating in this project you agree to abide by its terms. 289 | 290 | 291 | ## License 292 | 293 | Creative Commons License
Developer Onboarding by OpenCompany, LLC. is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. 294 | 295 | Copyright © 2015-2020 OpenCompany, LLC --------------------------------------------------------------------------------