{"id":49095253,"url":"https://github.com/bibendi/starmap","last_synced_at":"2026-04-20T20:04:38.813Z","repository":{"id":352301709,"uuid":"1148231501","full_name":"bibendi/starmap","owner":"bibendi","description":"Turns invisible team competencies into a map of capabilities. Reduces bus factor, highlights risks, plans development.","archived":false,"fork":false,"pushed_at":"2026-04-18T21:29:48.000Z","size":4621,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-18T23:22:30.447Z","etag":null,"topics":["bus-factor","engineering-management","hr-tech","ruby-on-rails","team-development"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bibendi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-02T18:20:27.000Z","updated_at":"2026-04-18T21:14:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bibendi/starmap","commit_stats":null,"previous_names":["bibendi/starmap"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/bibendi/starmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibendi%2Fstarmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibendi%2Fstarmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibendi%2Fstarmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibendi%2Fstarmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bibendi","download_url":"https://codeload.github.com/bibendi/starmap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibendi%2Fstarmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32063459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bus-factor","engineering-management","hr-tech","ruby-on-rails","team-development"],"created_at":"2026-04-20T20:04:37.635Z","updated_at":"2026-04-20T20:04:38.805Z","avatar_url":"https://github.com/bibendi.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starmap\n\n[![CI](https://github.com/bibendi/starmap/actions/workflows/ci.yml/badge.svg)](https://github.com/bibendi/starmap/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)](LICENSE)\n\nStarmap is an open-source web application that makes engineering team competencies visible and manageable. It turns invisible, distributed knowledge into a living map of technical capabilities — so teams can proactively identify risks, plan development, and reduce bus factor.\n\nIt is not a control system. Its goal is to help every team member see their progress, understand team priorities, and consciously plan their growth.\n\n\u003cdetails\u003e\n\u003csummary\u003eScreenshots\u003c/summary\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/attachments/team-dashboard.png\" width=\"600\" alt=\"Team Dashboard\"\u003e\u003cbr\u003e\n\u003cem\u003eTeam Dashboard\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/attachments/team-competency.png\" width=\"600\" alt=\"Team Competency\"\u003e\u003cbr\u003e\n\u003cem\u003eTeam Competency\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/attachments/unit-dashboard.png\" width=\"600\" alt=\"Unit Dashboard\"\u003e\u003cbr\u003e\n\u003cem\u003eUnit Dashboard\u003c/em\u003e\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n## Quick Start\n\n### Prerequisites\n\n- Ruby 3.3+\n- Node.js 20+\n- PostgreSQL 15+\n- Docker (optional: for PostgreSQL and Keycloak)\n\n### Setup\n\n```bash\ngit clone https://github.com/bibendi/starmap.git\ncd starmap\n\nbundle install\nnpm install\n\ndocker compose up -d          # PostgreSQL and Keycloak (optional)\nbin/rails db:setup            # creates DB, runs migrations, loads seed data\n\nbin/dev                        # starts Puma + Vite dev server\n```\n\nThe app runs at `http://localhost:3000`.\n\n### Authentication\n\nStarmap supports two authentication methods:\n\n**Email and password** — enabled by default, no configuration needed.\n\n**OpenID Connect (OIDC)** — if your organization uses a Single Sign-On provider (Keycloak, Google Workspace, Okta, Auth0, and others), you can enable OIDC login. Set the following environment variables:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OIDC_CLIENT_ID` | No | Client ID from your SSO provider. When set, enables OIDC login |\n| `OIDC_CLIENT_SECRET` | If OIDC enabled | Client secret from your SSO provider |\n| `OIDC_ISSUER` | If OIDC enabled | URL of your SSO realm (e.g. `https://auth.example.com/realms/my-org`) |\n| `REGISTRATION_ENABLED` | No | Show a \"Sign up\" link on the login page (`true`/`false`, default: `false`) |\n\nFor local development, a pre-configured Keycloak instance is included in `docker-compose.yml`:\n\n```bash\ndocker compose up -d keycloak   # starts at http://localhost:5101\n```\n\n## How It Works\n\n### Competency Scale (0-3)\n\nEvery rating answers the question: *\"What can I practically do with this technology right now?\"*\n\n| Level | Meaning |\n|-------|---------|\n| **0** | No prior experience. Needs an introduction from scratch |\n| **1** | Can work on simple tasks under guidance or pairing with a senior |\n| **2** | Can independently pick up a mid-complexity task and ship it to production |\n| **3** | Can explain architectural decisions, do code review, and mentor others |\n\n### Quarterly Cycle\n\nStarmap evaluates competencies **retrospectively** — after a quarter ends, not while it's in progress. The process repeats every quarter:\n\n1. **Quarter creation** — an admin creates a new quarter (e.g. \"2026 Q1\") after it has ended, sets the evaluation window dates\n2. **Activation \u0026 self-assessment** — the admin activates the quarter; previous quarter's ratings are copied as a starting point. Engineers then rate themselves asynchronously across team technologies during the evaluation window\n3. **1-on-1 dialogue** — team lead and engineer discuss ratings, sync on levels, and build a development plan\n4. **Close** — the admin closes the quarter; all remaining draft/submitted ratings are auto-approved. The quarter becomes read-only\n\nQuarter lifecycle: `draft` → `active` → `closed` → `archived`\n\n### User Roles\n\n| Role | Scope |\n|------|-------|\n| **Engineer** | Self-assessment, personal dashboard, action plans |\n| **Team Lead** | Team competency matrix, approve ratings, team planning |\n| **Unit Lead** | Unit-level metrics, risk reports, strategic development |\n| **Admin** | User/technology management, quarter lifecycle, system settings |\n\n## Metrics\n\nMetrics are like a car dashboard — they don't judge the driver, they help navigate. Their purpose is to highlight areas for discussion, not to deliver verdicts.\n\n### Team Health\n\nFour summary metrics give a quick overview:\n\n- **Coverage Index** — answers \"Is our team protected if someone leaves?\" Shows the percentage of technologies where enough people have expertise. Target: \u003e80%\n- **Maturity Index** — answers \"Are we growing as a team?\" Tracks the average competency level across all technologies over time. Target: \u003e2.0\n- **Red Zones** — answers \"Where are we most vulnerable?\" Lists critical technologies where too few people have expertise, putting delivery at risk\n- **Key Person Risks** — answers \"Who is carrying too much?\" Highlights technologies where only one person has expertise — a burnout risk and a single point of failure\n\n### Individual Growth\n\n- **Competency Dynamics** — answers \"Is this engineer growing?\" Shows rating change per person compared to the previous quarter. A starting point for 1-on-1 career discussions\n- **Universality Index** — answers \"Is this person a specialist or a generalist?\" Counts how many technologies someone is proficient in. Helps spot T-shaped contributors vs. deep specialists\n- **Expertise Concentration** — answers \"Is this person overloaded with unique knowledge?\" Counts technologies where someone is the only expert. A decrease is good — it means knowledge is being shared\n\n### Skill Matrix\n\nA visual grid of technologies vs. team members with:\n\n- **Bus Factor** — how many experts each technology has compared to the target\n- **Coverage %** — what share of the team can work with each technology\n\n## Deployment\n\nDocker images are published to GitHub Container Registry on every release tag:\n\n```bash\ndocker pull ghcr.io/bibendi/starmap:latest\n```\n\nImages are tagged with semver versions (`1.0.0`) and short SHAs.\n\nRequired environment variables when running the container:\n\n```bash\ndocker run -d \\\n  -p 3000:3000 \\\n  -e SECRET_KEY_BASE=your-secret \\\n  -e DATABASE_URL=postgres://user:pass@host:5432/starmap_production \\\n  ghcr.io/bibendi/starmap:latest\n```\n\n### Initial Setup\n\nAfter deploying for the first time, create the admin user:\n\n```bash\ndocker exec -it \u003ccontainer\u003e rails 'admin:create[\"admin@example.com\"]'\n```\n\nThis generates a random password and prints it to stdout. The task only works when no users exist in the database yet.\n\n## Monitoring\n\nStarmap exposes infrastructure metrics in Prometheus format via [Yabeda](https://github.com/yabeda-rb/yabeda). Metrics are available on a separate port to avoid exposing them publicly.\n\n### Endpoints\n\n| Endpoint | Default | Description |\n|----------|---------|-------------|\n| Prometheus metrics | `http://0.0.0.0:9394/metrics` | All application and server metrics |\n\nPort and path are configurable via environment variables: `PROMETHEUS_EXPORTER_PORT`, `PROMETHEUS_EXPORTER_PATH`, or `PROMETHEUS_EXPORTER_URL`.\n\n### Collected Metrics\n\n| Plugin | Description |\n|--------|-------------|\n| [yabeda-rails](https://github.com/yabeda-rb/yabeda-rails) | Request counts, duration, view and DB runtime |\n| [yabeda-activerecord](https://github.com/yabeda-rb/yabeda-activerecord) | SQL query performance, connection pool stats |\n| [yabeda-puma-plugin](https://github.com/yabeda-rb/yabeda-puma-plugin) | Puma workers, threads, backlog, pool capacity |\n\n### Adding Custom Metrics\n\nDefine custom metrics in `config/initializers/yabeda.rb`:\n\n```ruby\nYabeda.configure do\n  group :starmap do\n    counter :quarter_activations_total,\n            comment: \"Total number of quarter activations\",\n            tags: [:unit_id]\n\n    gauge :skill_ratings_pending,\n          comment: \"Number of ratings awaiting approval\",\n          tags: [:team_id]\n  end\nend\n```\n\n## Testing\n\n### Ruby (RSpec)\n\n```bash\nbundle exec rspec                           # all tests\nbundle exec rspec --tag n_plus_one          # N+1 query tests only\nLOG=all bundle exec rspec spec/path:42      # with SQL logging\n```\n\n### JavaScript (Vitest)\n\n```bash\nnpm test                   # all tests\nnpm run test:watch         # watch mode\nnpm run test:coverage      # with coverage\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Make your changes with tests\n4. Run `bundle exec rspec` and `npm test`\n5. Run `bundle exec rubocop` and `npm run check:js`\n6. Open a Pull Request\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbibendi%2Fstarmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbibendi%2Fstarmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbibendi%2Fstarmap/lists"}