Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1# Welcome to Coop!
2
3
4
5## What is Coop?
6
7This repository is home to one of ROOST’s tools; the Coop review tool. Coop originated as a SaaS company called Cove, and has been given a new open source software life by ROOST as Coop.
8
9Coop provides a comprehensive solution for online safety that includes:
10* **Review Console**: Human review interface for complex moderation decisions
11* **Content Processing**: Support for posts, comments, media, and custom content types
12* **Analytics**: Detailed insights into moderation effectiveness and trends
13* **Rules Engine**: Automated content evaluation against customizable policies
14* **API Integration**: Simple REST and GraphQL APIs for seamless platform integration
15
16### v0 Release
17This is an early v0 release of Coop. We've focused on getting core review capabilities and child safety workflows into a usable state, but there's still active development ahead. You can expect features and documentation that will evolve based on community feedback.
18
19We're developing Coop in the open and want to hear from you! Whether you're testing it out, running into issues, or have ideas for improvements, please open an [issue](https://github.com/roostorg/coop/issues/new/choose) or join our [Discord](https://discord.gg/5Csqnw2FSQ). Your feedback directly shapes the [roadmap](https://github.com/roostorg/community/blob/main/roadmap.md).
20
21## Technology Stack
22
23 Coop includes:
24
25* **API Server:** Node.js/TypeScript-based REST and GraphQL APIs.
26* **Frontend**: React-based client application, AntDesign, GraphQL, TailwindCSS
27* **Infrastructure**: Docker, Kubernetes
28* **Model Service:** Python-based machine learning services.
29* **Databases**: PostgreSQL, ClickHouse, Scylla
30* **Caching**: Redis
31* **Utility Services**: Database migrators, instrumentation, and proxy layers.
32
33## Getting Started
34For development on Coop it is recommended to:
35
36- use a machine with 16 GiB RAM or more
37- use Node 24 (run `nvm install && nvm use` so local matches `.nvmrc`)
38
39and then follow the steps below:
40
411. On the root directory run command `npm run up` afterwards you want to have 3 different terminals open.
42
43 Make sure all backing services (`postgres`, `clickhouse`, `scylla`, etc.) are up and running. (Scylla is needed for user data.)
44
452. Install dependencies for the root, `client`, `server`, and `db` packages:
46 ```bash
47 npm install
48 (cd client && npm install)
49 (cd server && npm install)
50 (cd db && npm install)
51 ```
523. Make sure the `.env` files for `/server` and `db` are populated (including ClickHouse credentials). Run database migrations:
53 ```bash
54 npm run db:update -- --env staging --db api-server-pg
55 npm run db:update -- --env staging --db scylla
56 npm run db:update -- --env staging --db clickhouse
57 ```
58### Alternative: Single Command for Steps 2-3
59
60You can combine the dependency installation and database migrations into a single command:
61
62```bash
63npm install \
64 && (cd client && npm install) \
65 && (cd server && npm install) \
66 && (cd db && npm install) \
67 && npm run db:update -- --env staging --db api-server-pg \
68 && npm run db:update -- --env staging --db clickhouse
69```
70
714. On the terminals you want to run on each the following commands:
72 1. `npm run client:start`
73 2. `npm run server:start`
74 3. `npm run generate:watch` — Optional for GraphQL changes, but good to keep track as you make them
75 This will help keep the logs for each of them separate for easy debugging.
76
775. Create an organization and admin user:
78```bash
79 npm run create-org
80```
81
82Use the credentials provided to log in at `http://localhost:3000`.
83Please note that the initial page load may take a while.
84
85
86### **Database Structure and Migrations**
87
88All of the data around the database tables ( SQL/Schema ) exist under the `db/src/scripts` folder where there is a folder for each service (for example `api-server-pg`, `clickhouse`, `scylla`).
89
90### **Management Scripts**
91
92The `server/bin` folder contains utility scripts for managing the Coop server:
93
94- **Create Organization**: Use `npm run create-org` to create a new organization with an admin user and API key.
95- **Get Invite Token**: Use `npm run get-invite` to retrieve the signup link for a user invited from the UI.
96
97See `server/bin/README.md` for detailed usage instructions and examples.
98
99# Code Structure
100
101Server Code ( `/server` ):
102
103Contains all of the back-end service that powers the API server this is divided in 3 parts:
104
105* REST API: Handles most of Customers (Users) requests for content moderation.
106* GraphQL API: This is the API endpoints powering the front-end app and it is called by customers when interacting with the front-end.
107* Static Assets: Serves static assets that powers part of the front-end ( JS Bundle, Images, etc.. )
108
109Backend primarily works using dependency injection using [BottleJS](https://github.com/young-steveo/bottlejs) as a way to power lazy loading, middleware hooks, and decorators. This is all declared on the `/iocContainer` [folder](https://github.com/roostorg/coop/blob/main/server/iocContainer/index.ts) When declaring a new service this is where you start to build it and make it available where needed.
110
111`/routes` Contains the API routes that power user submissions and actions.
112
113## GraphQL
114
115GraphQL is used for communication between front-end and back-end services. The code is generated in both places as changes to mutations, resolvers, and types are done. To ensure the code is generated you want to run `npm run generate` on the root of the repository or keep the watch option running.
116
117> [!NOTE]
118> Careful around this as each change will generate code for both which will in turn trigger the recompile of both front-end and back-end.
119
120Most back-end defined GraphQL can be found by searching the annotation `/* GraphQL */` which is added at the beginning of each GraphQL block, and most likely in the `/server/graphql` directory
121
122Front-end on the other hand is defined across different places where it may be used, but by nature that also means a file may use GraphQL that is not defined inside it.
123
124Considerations: Consolidate GraphQL code on a better folder structure.
125
126
127## Key Features
128### Manual Review Interface
129Intuitive moderator console with queue management, dynamic content rendering, and comprehensive review tools.
130
131### Automated Moderation
132Powerful rules engine that evaluates content against customizable policies using signals like toxicity detection, keyword matching, and custom logic.
133
134### Easy Integration
135Simple REST and GraphQL APIs that integrate seamlessly with existing platforms and applications.
136### Analytics & Insights
137Detailed analytics on moderation effectiveness, rule performance, and content trends.
138
139### Scalable Architecture
140Built on modern cloud infrastructure with horizontal scaling, caching, and performance optimization.
141
142## Deployment
143
144For historical reference, AWS infrastructure code (CDK, Helm charts, Pulumi, CDKTF) that was previously used for production deployments is available on the [`0.1` branch](https://github.com/roostorg/coop/tree/0.1/.devops). That infrastructure code may have drifted from the current application architecture and is no longer maintained, but can serve as a reference for your own deployment.
145
146## Documentation
147
148The `/docs` folder includes detailed guides on the UI, architecture, key concepts, how signals in Coop work, and how to get started.
149
150### Contributors
151
152We welcome contributions from the community\! Coop benefits from diverse perspectives and expertise in building safer online spaces.
153
154### **How to Contribute**
155
156Please read our [Contributing Guide](https://github.com/roostorg/.github/blob/main/CONTRIBUTING.md) for details on:
157
158* Ways to contribute (code, documentation, testing, rules)
159* Development workflow and setup
160* Code review process and timeline
161* Community guidelines
162
163
164### Join Us
165
166Writing code is not the only way to help the project. Reviewing pull requests, answering questions to help others on mailing lists or issues, providing feedback from a domain expert perspective, organizing and teaching tutorials, working on the website, improving the documentation, are all priceless contributions.
167
168* Join us on [Discord](https://discord.gg/HJevKCEN)
169 * General discussion channel \#general
170 * Development discussions \#coop
171* Join our [newsletter](https://roost.tools/#get-started) for more announcements and information
172* Follow us on [LinkedIn](https://www.linkedin.com/company/roost-tools/) or [Bluesky](https://bsky.app/profile/roost.tools)