University of Peradeniya crestSCS Documentation
University of Peradeniya crestSCS Documentation
Department website

Start here

Repository handbookRepository overviewDevelopment

System design

ArchitectureAuthentication and authorizationPublic dataAPI contractsSchemas
UI system

Applications

Department Web applicationPeople applicationProjects applicationPortal application

Services

API serviceGitHub App serviceMailer service
Service internals
GitHub App internalsGitHub App durable operationsGitHub App repository mutationsGitHub App runtime and recovery

Shared packages

Schemas packageUI packageTypeScript configuration packageESLint configuration package

Development workflow

Testing and verificationDependency managementDocumentation authoringUI quality assurance

Operations

Continuous integrationEnvironment variablesOperationsSecurityTroubleshooting

Reference

Route referenceGlossary
Service internalsGitHub App service

Source map, trust boundary, domain ownership, and verification guide for Git-backed automation.

GitHub App internals

services/github-app turns authorized internal commands into reviewable Git changes. It is the only service in this monorepo that holds GitHub App credentials. Browser code must never call it directly.

Source map

AreaSourceResponsibility
Worker entrysrc/index.tsvalidates runtime configuration, serves HTTP, consumes queue batches, and exports Durable Objects
Local entrysrc/server.tsruns the same Hono application under Bun with process-local operation state
HTTP compositionsrc/app.tsmounts authenticated operation and repository route families
Controllerssrc/controllersvalidate transport input and translate domain results to HTTP
Durable runtimesrc/operationsoperation identity, persistence, queue dispatch, retries, cancellation, and resource leases
Domain operationssrc/domainsprofile, project, and academic commands, projections, and draft repositories
Direct PR repositoriessrc/repositoriessynchronous profile, project, course, and student-placement PR workflows, including index reconciliation
GitHub adapterssrc/githubApp authentication, provider calls, snapshots, atomic commits, PR lookup, and error classification
Contracts@scs/schemasoperation envelopes, status/outcome types, and public-data records

Trust boundary

The authentication middleware compares X-Internal-Secret with X_INTERNAL_SECRET using SHA-256 digests and a timing-safe comparison. That proves the request came through the trusted service boundary; controllers then validate any actor headers and payloads they depend on. The secret is not a browser token and must never be exposed by Portal or API responses.

Operation status and cancellation additionally require X-Actor-Subject-Id. A non-admin actor may access only an operation whose stored actor subject matches. X-Actor-Admin: true is trusted only because the request has already passed internal-service authentication.

Domain ownership

  • Durable profile operations commit the authoritative person file and record aggregate targets in PR metadata. The direct PR repository also reconciles aggregate lists and the public People search index.
  • Durable project operations commit or delete the authoritative project file. The direct PR repository also reconciles the project aggregate, manifest, and affected per-person indexes.
  • Courses and offerings update their authoritative academic record through an atomic Git commit.
  • Student placement updates the registry metadata that determines programme, stream, department, batch, alumni, and postgraduate interpretation.

Detailed guides:

  • Durable operations covers identity, state, serialization, retries, cancellation, and queue behavior.
  • Repository mutations covers snapshots, revisions, atomic commits, pull requests, and projections.
  • Runtime and recovery covers Cloudflare and local modes, bindings, observability, failure categories, and recovery boundaries.

Verification map

Tests cover operation idempotency, concurrency, recovery, authorization, GitHub error classification, atomic commits, gateways, each domain operation and projection, repository behavior, and aggregate reconciliation.

bun --filter '@scs/github-app' lint
bun --filter '@scs/github-app' typecheck
bun --filter '@scs/github-app' typecheck:test
bun --filter '@scs/github-app' test
bun --filter '@scs/github-app' knip
bun --filter '@scs/github-app' build

API public-data mutations

How profile, project, course, and offering reads and Git-backed changes are authorized and orchestrated.

GitHub App durable operations

Operation identity, persistence, queue execution, resource serialization, retries, and cancellation semantics.

On this page

GitHub App internalsSource mapTrust boundaryDomain ownershipVerification map