https://github.com/alkem-io/server
Core server in the Alkemio platform, offering a GraphQL api for interacting with the logical domain model.
https://github.com/alkem-io/server
challenges docker graphql graphql-api graphql-server node projects society typeorm typescript
Last synced: 5 months ago
JSON representation
Core server in the Alkemio platform, offering a GraphQL api for interacting with the logical domain model.
- Host: GitHub
- URL: https://github.com/alkem-io/server
- Owner: alkem-io
- License: eupl-1.2
- Created: 2020-08-23T06:54:12.000Z (almost 6 years ago)
- Default Branch: develop
- Last Pushed: 2025-10-23T16:34:46.000Z (8 months ago)
- Last Synced: 2025-10-23T18:30:20.497Z (8 months ago)
- Topics: challenges, docker, graphql, graphql-api, graphql-server, node, projects, society, typeorm, typescript
- Language: TypeScript
- Homepage: http://alkem.io
- Size: 33.4 MB
- Stars: 27
- Watchers: 10
- Forks: 5
- Open Issues: 348
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Empowering society. The platform to succeed in working on challenges, together.
# Alkemio Server
Welcome to the Alkemio Server! This server is the heart of the Alkemio Platform, and manages the representation of the Space and all the entities stored wthin it.
[](https://travis-ci.com/github/alkem-io/server)
[](https://coveralls.io/github/alkem-io/server?branch=develop)
A high level overview of the Design of the Alkemio Server is shown below.
The server primarily interacts via a _*GraphQL api*_' that it exposes. This can be found at the following location: (assuming default port).
This api is used by the [Alkemio Web Client](http://github.com/alkem-io/client-web), but also by any other clients / integrations that need to interact with the Alkemio server.
The key takeaway is that the Alkemio server is designed to be integrated, so that other tools or user interfaces can make use of the logical domain model maintained by the server.
## **Additional information**:
- [Design - An overview of architectural layers and technologies used](docs/Design.md)
- [Running - How to run the Server using containers (docker-compose and docker)](docs/Running.md)
- [Developing - How to setup the Server for developing](docs/Developing.md)
- [Data Management - How data representing the domain model used by Alkemio Platform is managed, including database migrations](docs/DataManagement.md)
- [Quality Assurance - Details of the test harness around the server and how to execute the test suites](docs/QA.md).
- [Pushing - How new docker images are published to Dockerhub](docs/PublishingImages.md)
- [Database definitions - Guidelines for creating TypeORM entity definitions](docs/database-definitions.md)
For other questions / comments please feel free to reach out via the channels listed in the [Alkemio Repo](http://github.com/alkem-io/alkemio) or via [Alkemio organization](https://alkemio.org).
## GraphQL Schema Contract Governance
The GraphQL schema is treated as a stable contract. Every schema-affecting change is diffed against the committed canonical snapshot (`schema.graphql`) using an automated toolchain (Feature 002: Schema Contract Diffing & Enforcement).
Key points:
- Deterministic snapshot: `npm run schema:print` (+ optional `npm run schema:sort`) produces a canonical `schema.graphql`.
- Change classification: Diffs produce `change-report.json` categorizing entries as ADDITIVE, DEPRECATED, DEPRECATION_GRACE, INVALID_DEPRECATION_FORMAT, BREAKING, PREMATURE_REMOVAL, INFO, or BASELINE.
- Deprecation lifecycle: Deprecations must use the format `REMOVE_AFTER=YYYY-MM-DD | reason`. A 90‑day minimum window applies to removals (fields + enum values). Missing schedule initially yields a 24h `DEPRECATION_GRACE` warning.
- Overrides: Intentional breaking changes require a CODEOWNER GitHub review containing the phrase `BREAKING-APPROVED`. Approved entries show `overrideApplied` and pass the gate.
- CI gate: Unapproved BREAKING, PREMATURE_REMOVAL, or INVALID_DEPRECATION_FORMAT changes fail the `schema-contract` workflow.
- Performance budget: Large schema diff executes in <5s (enforced by perf test).
Developer workflow summary:
1. Update code.
2. Regenerate snapshot (`npm run schema:print && npm run schema:sort`).
3. Fetch prior snapshot (from base branch) and run diff (`npm run schema:diff`).
4. Review classifications; if intentional breaking, secure CODEOWNER approval with phrase.
5. Commit updated `schema.graphql` only.
See `specs/002-schema-contract-diffing/quickstart.md` for full instructions, troubleshooting, and classification glossary.
### CLI Quick Reference (Schema Contract Tooling)
Core scripts (all TypeScript runners use ts-node + path mapping):
| Intent | Command | Notes |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| Print current schema | `npm run schema:print` | Generates `schema.graphql` (lightweight bootstrap under env `SCHEMA_BOOTSTRAP_LIGHT=1`) |
| Canonical sort | `npm run schema:sort` | Stable lexicographic ordering (idempotent) |
| Diff vs previous | `npm run schema:diff` | Requires `tmp/prev.schema.graphql` (empty => baseline) writes `change-report.json` & `deprecations.json` |
| Validate artifacts | `npm run schema:validate` | Ajv validation against JSON Schemas |
Governance environment variables:
| Variable | Purpose |
| --------------------------------- | -------------------------------------------------------------------------------- |
| `SCHEMA_BOOTSTRAP_LIGHT` | When `1`, uses lightweight module for faster printing (parity enforced by tests) |
| `SCHEMA_OVERRIDE_CODEOWNERS_PATH` | Alternate path to `CODEOWNERS` file |
| `SCHEMA_OVERRIDE_REVIEWS_JSON` | Inline JSON array of review objects (`[{reviewer, body, state}]`) |
| `SCHEMA_OVERRIDE_REVIEWS_FILE` | Path to file containing JSON reviews array |
Override approval phrase: `BREAKING-APPROVED` (must appear in APPROVED review body by a CODEOWNER reviewer). Applies to BREAKING entries only; sets `overrideApplied=true` and per-entry `override=true` so gate treats them as informational.
Workflow note: the `schema-contract` GitHub Action automatically fetches PR reviews, writes them to `tmp/schema-override-reviews.json`, and re-applies override evaluation during both the diff and gate steps. After each push, submit a fresh CODEOWNER approval review containing `BREAKING-APPROVED`, then re-run the workflow so the new review is ingested.
Exit codes (schema gate):
| Code | Meaning | Blocking Condition |
| ---- | -------------------------- | -------------------------------------------------------- |
| 0 | Success | No unapproved blocking classifications |
| 1 | BREAKING | One or more BREAKING entries without override |
| 2 | PREMATURE_REMOVAL | Removal attempted before lifecycle conditions met |
| 3 | INVALID_DEPRECATION_FORMAT | Malformed or missing removal schedule after grace period |
Performance budgets: diff <5s on synthetic 250+ type schema; cold bootstrap <2s (enforced by automated tests).
## Schema gate runner flags
The CI runner script `.github/workflows/scripts/schema-gate.ts` accepts a small CLI:
- `--path=` (or positional ``): path to the change report JSON (defaults to `change-report.json`).
- `--fail` / `--no-fail`: boolean toggle to make the script exit non-zero on detected violations.
Per-entry overrides are honored via the `override` boolean on change entries. `INVALID_DEPRECATION_FORMAT` entries are treated as warnings (non-blocking) by default; this behavior can be changed if desired in the script.
For deeper glossary, lifecycle rules, simulation of overrides, troubleshooting, see the Quickstart.