Sefism is free for learners. We are here to help you grow, one step at a time.Join for free
Sefism.
Cloud & DevOps

Lightweight Internal Developer Portal with Service Scorecards

A small internal developer portal for engineering teams of 10 to 50 people: a service catalogue built from files in each repository, scorecards that check production readiness, and templates that create a new service with CI, Dockerfile and monitoring in one step. An intermediate cloud and DevOps final year project in platform engineering.

Topics
Difficulty

Intermediate

A small team, or one strong student willing to learn something new.
Effort

2 semesters · 3 students

Deliverables

6 to ship

3 optional extras

Suggested stack

TypeScriptNext.jsPostgreSQLGitHub App and REST APIYAML catalogue filesCookiecutter-style templates
A suggestion, not a requirement. Swap anything for what you already know.

What you should ship

  • A GitHub App that discovers repositories, reads a catalogue file from each (owner, type, dependencies, runbook link, on-call contact) and keeps the catalogue in sync on every push.
  • A searchable catalogue with service pages showing owner, dependencies, recent deploys, open incidents link and documentation.
  • Scorecards with at least eight checks (has an owner, CI passes on main, Dockerfile uses a pinned base image, has a health endpoint, has a runbook, dependency updates enabled and so on), evaluated automatically.
  • A golden-path template flow that creates a new repository with CI, a Dockerfile, a health check and a catalogue file already filled in, and registers it in the catalogue.
  • A weekly team digest showing scorecard changes and the top three fixes per team.
  • A pilot with a real team and a before-and-after measurement of scorecard results and time to create a new service.

If you have time left

  • A dependency graph view with blast-radius highlighting: which services are affected if this one fails.
  • Scorecard checks written as small plug-ins so teams can add their own without editing core code.
  • Import of existing Backstage catalogue files so teams can move either way.

The problem: nobody knows who owns what

Once a company has more than a handful of services, simple questions become hard. Who owns the payments service? Where is its runbook? Does it have a health check? Which services call it? Answers live in people's heads, a stale wiki page and a spreadsheet someone started once. New joiners spend weeks asking around, and every new service is set up slightly differently because people copy whatever repository they last worked on.

Platform engineering answers this with an internal developer portal: one place for the service catalogue, production-readiness standards and paved roads for creating new things. Spotify built Backstage for this and open-sourced it. The pattern is sound, but the effort to run it is sized for larger organisations.

What already exists and the gap

  • Backstage, from Spotify and now a CNCF project, is the open source standard, very extensible, and widely reported to need dedicated engineers to set up and maintain.
  • Port, Cortex and OpsLevel are commercial portals with catalogues, scorecards and self-service actions, priced for companies with platform budgets.
  • Roadie offers hosted Backstage for teams that want it without running it.

The gap is a portal a team of 10 to 50 engineers can install in an afternoon, driven by files in their own repositories, with opinionated default scorecards and one good template, and nothing else to maintain.

What you build

  • Catalogue sync: a GitHub App that listens for pushes, reads the catalogue file, validates it and updates the database. Repositories without the file appear as "unclaimed".
  • Service pages: owner, links, dependencies (declared in the file, optionally checked against real calls), recent deploys from the CI system.
  • Scorecards: checks run on a schedule and on push using the GitHub API and repository contents. Each check has a clear pass rule and a "how to fix" link.
  • Templates: a form that asks for a name, owner and language, then creates a repository from a template, fills in values and opens it ready to deploy.
  • Digest: a weekly message per team with what improved and what to fix next.

The technically interesting part

The difficult part is keeping the catalogue correct without asking people to maintain it. Declared data (the YAML file) and observed data (CI status, Dockerfile contents, branch protection) disagree, and you need rules for which wins and how to surface the disagreement. Scorecard checks must be cheap to run across every repository without hitting API rate limits, which calls for caching, conditional requests and incremental re-evaluation on push. Show your evaluators the sync design, how rate limits are respected, and how a check result is traced back to evidence.

How to evaluate it

  • Setup time: time for a new team to install the app and see a populated catalogue, measured with two or three teams.
  • Accuracy: for a sample of scorecard results, manually verify each check; report false passes and false fails.
  • Freshness and cost: seconds from a push to an updated service page, and API calls used per repository per day.
  • Template value: time to create a deployable new service with and without the template, with at least five developers.
  • Adoption: over a four-week pilot, how many services moved up at least one scorecard level.

Suggested plan

  1. Semester 1, weeks 1 to 4: catalogue file format, GitHub App and sync.
  2. Weeks 5 to 9: catalogue UI and service pages.
  3. Weeks 10 to 14: first eight scorecard checks with caching.
  4. Semester 2, weeks 1 to 5: golden-path template flow and team digests.
  5. Weeks 6 to 10: pilot with a real team (a software house, a startup or a large university project group).
  6. Weeks 11 to 14: evaluation and write-up.

Path to a product

The first customer is a software house or product company with 15 to 40 engineers and no platform team, where onboarding and inconsistent services are daily pain. Offer a free self-hosted version and charge for hosted use per engineer, keeping it well below the enterprise portals. Software houses that build for many clients are a strong market because consistent project set-up directly saves billable hours.

Scope warning

Do not rebuild Backstage's plug-in system, a documentation site generator or incident management. Support GitHub only. Do not build self-service infrastructure provisioning (databases, clusters) in the first version; one repository template is enough to prove the golden path.

Learn what you need on Sefism

Get help with this idea

Choosing the right eight scorecard checks, and a pilot team willing to use them, is worth a conversation before you start. A mentor can help you set the scope, pick a stack you can finish with, and design an evaluation your examiners will respect. The build is yours; the guidance is on scope, stack and evaluation. New here? Create a free account first.

Ideas and guidance, not finished projects

These are project ideas and scoping guidance, published free for students to use as a starting point. I do not build, write, or sell final-year projects, and I do not complete coursework for anyone. Take an idea, make it yours, and build it.

Not sure this one fits you?

I help students pick an idea that matches their skills and their deadline, then scope it down until it is finishable. Guidance only, never done for you.

Discuss this idea
Work with me

Stuck on something specific?

Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.

Book a free sessionSee all services

Follow along

New writing, resources and project ideas land here first.