{"id":14976060,"url":"https://github.com/alkem-io/server","last_synced_at":"2026-02-10T01:05:20.140Z","repository":{"id":36969258,"uuid":"289632902","full_name":"alkem-io/server","owner":"alkem-io","description":"Core server in the Alkemio platform, offering a GraphQL api for interacting with the logical domain model. ","archived":false,"fork":false,"pushed_at":"2025-10-23T16:34:46.000Z","size":34979,"stargazers_count":27,"open_issues_count":348,"forks_count":5,"subscribers_count":10,"default_branch":"develop","last_synced_at":"2025-10-23T18:30:20.497Z","etag":null,"topics":["challenges","docker","graphql","graphql-api","graphql-server","node","projects","society","typeorm","typescript"],"latest_commit_sha":null,"homepage":"http://alkem.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alkem-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-08-23T06:54:12.000Z","updated_at":"2025-10-23T10:45:39.000Z","dependencies_parsed_at":"2023-12-21T12:42:40.964Z","dependency_job_id":"e28b3499-3317-4b5e-8c31-e13643540a7a","html_url":"https://github.com/alkem-io/server","commit_stats":{"total_commits":4683,"total_committers":31,"mean_commits":"151.06451612903226","dds":0.6073030108904549,"last_synced_commit":"81516b18485aa573f61d908cfeaef89c570ece3e"},"previous_names":[],"tags_count":460,"template":false,"template_full_name":null,"purl":"pkg:github/alkem-io/server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkem-io%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkem-io%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkem-io%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkem-io%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alkem-io","download_url":"https://codeload.github.com/alkem-io/server/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alkem-io%2Fserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281319772,"owners_count":26481061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-27T02:00:05.855Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["challenges","docker","graphql","graphql-api","graphql-server","node","projects","society","typeorm","typescript"],"created_at":"2024-09-24T13:53:14.260Z","updated_at":"2025-12-12T01:39:58.153Z","avatar_url":"https://github.com/alkem-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://alkemio.org/\" target=\"blank\"\u003e\u003cimg src=\"https://alkem.io/logo.png\" width=\"400\" alt=\"Alkemio Logo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ci\u003eEmpowering society. The platform to succeed in working on challenges, together.\u003c/i\u003e\u003c/p\u003e\n\n# Alkemio Server\n\nWelcome 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.\n\n[![Build Status](https://api.travis-ci.com/alkem-io/server.svg?branch=develop)](https://travis-ci.com/github/alkem-io/server)\n[![Coverage Status](https://coveralls.io/repos/github/alkem-io/server/badge.svg?branch=develop)](https://coveralls.io/github/alkem-io/server?branch=develop)\n![Docker Image CI](https://github.com/alkem-io/server/actions/workflows/build-release-docker-hub.yml/badge.svg)\n\nA high level overview of the Design of the Alkemio Server is shown below.\n\n\u003cp \u003e\n\u003cimg src=\"docs/images/alkemio-server-design.png\" alt=\"Component Diagram\" width=\"600\" /\u003e\n\u003c/p\u003e\n\nThe server primarily interacts via a _*GraphQL api*_' that it exposes. This can be found at the following location: \u003chttp://localhost:4000/graphql\u003e (assuming default port).\n\nThis 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.\n\nThe 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.\n\n## **Additional information**:\n\n- [Design - An overview of architectural layers and technologies used](docs/Design.md)\n- [Running - How to run the Server using containers (docker-compose and docker)](docs/Running.md)\n- [Developing - How to setup the Server for developing](docs/Developing.md)\n- [Data Management - How data representing the domain model used by Alkemio Platform is managed, including database migrations](docs/DataManagement.md)\n- [Quality Assurance - Details of the test harness around the server and how to execute the test suites](docs/QA.md).\n- [Pushing - How new docker images are published to Dockerhub](docs/PublishingImages.md)\n- [Database definitions - Guidelines for creating TypeORM entity definitions](docs/database-definitions.md)\n\nFor 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).\n\n## GraphQL Schema Contract Governance\n\nThe 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 \u0026 Enforcement).\n\nKey points:\n\n- Deterministic snapshot: `npm run schema:print` (+ optional `npm run schema:sort`) produces a canonical `schema.graphql`.\n- Change classification: Diffs produce `change-report.json` categorizing entries as ADDITIVE, DEPRECATED, DEPRECATION_GRACE, INVALID_DEPRECATION_FORMAT, BREAKING, PREMATURE_REMOVAL, INFO, or BASELINE.\n- 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.\n- Overrides: Intentional breaking changes require a CODEOWNER GitHub review containing the phrase `BREAKING-APPROVED`. Approved entries show `overrideApplied` and pass the gate.\n- CI gate: Unapproved BREAKING, PREMATURE_REMOVAL, or INVALID_DEPRECATION_FORMAT changes fail the `schema-contract` workflow.\n- Performance budget: Large schema diff executes in \u003c5s (enforced by perf test).\n\nDeveloper workflow summary:\n\n1. Update code.\n2. Regenerate snapshot (`npm run schema:print \u0026\u0026 npm run schema:sort`).\n3. Fetch prior snapshot (from base branch) and run diff (`npm run schema:diff`).\n4. Review classifications; if intentional breaking, secure CODEOWNER approval with phrase.\n5. Commit updated `schema.graphql` only.\n\nSee `specs/002-schema-contract-diffing/quickstart.md` for full instructions, troubleshooting, and classification glossary.\n\n### CLI Quick Reference (Schema Contract Tooling)\n\nCore scripts (all TypeScript runners use ts-node + path mapping):\n\n| Intent               | Command                   | Notes                                                                                                    |\n| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |\n| Print current schema | `npm run schema:print`    | Generates `schema.graphql` (lightweight bootstrap under env `SCHEMA_BOOTSTRAP_LIGHT=1`)                  |\n| Canonical sort       | `npm run schema:sort`     | Stable lexicographic ordering (idempotent)                                                               |\n| Diff vs previous     | `npm run schema:diff`     | Requires `tmp/prev.schema.graphql` (empty =\u003e baseline) writes `change-report.json` \u0026 `deprecations.json` |\n| Validate artifacts   | `npm run schema:validate` | Ajv validation against JSON Schemas                                                                      |\n\nGovernance environment variables:\n\n| Variable                          | Purpose                                                                          |\n| --------------------------------- | -------------------------------------------------------------------------------- |\n| `SCHEMA_BOOTSTRAP_LIGHT`          | When `1`, uses lightweight module for faster printing (parity enforced by tests) |\n| `SCHEMA_OVERRIDE_CODEOWNERS_PATH` | Alternate path to `CODEOWNERS` file                                              |\n| `SCHEMA_OVERRIDE_REVIEWS_JSON`    | Inline JSON array of review objects (`[{reviewer, body, state}]`)                |\n| `SCHEMA_OVERRIDE_REVIEWS_FILE`    | Path to file containing JSON reviews array                                       |\n\nOverride 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.\n\nWorkflow 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.\n\nExit codes (schema gate):\n\n| Code | Meaning                    | Blocking Condition                                       |\n| ---- | -------------------------- | -------------------------------------------------------- |\n| 0    | Success                    | No unapproved blocking classifications                   |\n| 1    | BREAKING                   | One or more BREAKING entries without override            |\n| 2    | PREMATURE_REMOVAL          | Removal attempted before lifecycle conditions met        |\n| 3    | INVALID_DEPRECATION_FORMAT | Malformed or missing removal schedule after grace period |\n\nPerformance budgets: diff \u003c5s on synthetic 250+ type schema; cold bootstrap \u003c2s (enforced by automated tests).\n\n## Schema gate runner flags\n\nThe CI runner script `.github/workflows/scripts/schema-gate.ts` accepts a small CLI:\n\n- `--path=\u003cfile\u003e` (or positional `\u003cfile\u003e`): path to the change report JSON (defaults to `change-report.json`).\n- `--fail` / `--no-fail`: boolean toggle to make the script exit non-zero on detected violations.\n\nPer-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.\n\nFor deeper glossary, lifecycle rules, simulation of overrides, troubleshooting, see the Quickstart.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falkem-io%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falkem-io%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falkem-io%2Fserver/lists"}