Build a code-hosting application

This guide builds a small code-hosting application on Enroute. The examples use TypeScript and Next.js. The same architecture works with any application that can call gRPC and serve HTTP.

You start with an empty application and add one working capability in each chapter. By the end, users can clone and push repositories, and the application can display files, history, and diffs.

What Enroute and your application do

Enroute serves Git traffic and stores Git data. Your application owns the product model: repository paths, users, permissions, and policy.

Git client -- Git smart HTTP --> Enroute <-- gRPC ------- application
                                    |
                                    +---- signed HTTP hooks --> application

The application implements two integration points:

Component	Direction	Purpose
gRPC client	Application to Enroute	Create repositories, read Git data, and update refs
HTTP hook endpoint	Enroute to application	Resolve identity and apply Git policy

Neither component implements the Git protocol.

Before you start

Complete the Quickstart. It installs enroute and starts it locally with enroute dev. This guide assumes Git listens on 127.0.0.1:8080 and gRPC listens on 127.0.0.1:50051.

To follow the examples, install Node.js 20 or later, Git, and protoc. Generated field names can differ in other protobuf toolchains. The TypeScript examples use lowerCamelCase names generated by ts-proto.

Chapters

Read the chapters in order. Each chapter uses the application created by the previous one.

Git integration

#	Chapter	You will add
1	Set up Enroute and your app	A local application and generated gRPC client
2	Create repositories	Application tables and repository creation
3	Handle hooks	A verified hook endpoint
4	Authenticate Git clients	Token-based clone access
5	Process pushes	Push policy and post-push messages

Repository UI

#	Chapter	You will add
6	Browse repositories	Branch, tree, and file pages
7	Read commits and diffs	History and diff pages

Using the guide

The code is a complete example application. It stores application data in its own Postgres database and uses Drizzle for database access. Enroute needs no database, so chapter 2 starts one for the application.

Copy the example, then adapt it to your application. Use the hook reference for hook fields and the API contract for RPC behavior. The guide explains one implementation; those references define the rules every implementation must follow.

After chapter 7, use Patterns for repository lifecycle, protected branches, merge requests, queues, checks, private access, deploy keys, CI, and mirroring.