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 starts Enroute and Postgres locally. This guide assumes Git listens on 127.0.0.1:8080, gRPC listens on 127.0.0.1:50051, and you can edit config/tenants.toml.

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 application	A local application and generated gRPC client
2	Create repositories	Application tables and repository creation
3	Handle hooks	A verified hook endpoint
4	Authorize 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 keeps its own schema in the same Postgres server; the two schemas do not share tables.

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.