Related Pages

Related topics: SDK Primitives & Resource Declarations, Parser & Code Generation Pipeline, Runtime, CLI & Deployment

Encore Overview & System Architecture

Project Purpose & Scope

Encore is an open-source backend development framework and toolchain whose top-level goal is to let developers define backend services and infrastructure declaratively, in source code, while the toolchain handles local execution, build, and deployment concerns. The repository is the canonical home for the framework: it ships a CLI, runtime libraries, and supporting tooling that together form the developer experience described in the project README Source: README.md:1-40. The framework is language-targeted primarily at Go, with auxiliary components implemented in Rust where performance or systems-level behavior is required. As shown by the recent security advisory release v1.57.11, the project actively maintains both the CLI distribution and the runtime that ends up deployed in user environments, treating them as a single coordinated artifact Source: README.md:1-20.

The intended scope is the entire backend lifecycle: scaffolding a project, compiling user code, parsing application source for declarative API and infrastructure definitions, running services locally, producing deployment artifacts, and (in managed usage) coordinating with the Encore Cloud platform. The CLI binary is the orchestrator that ties these phases together.

Repository Layout & Language Stack

The repository is polyglot. The Go side is declared as a Go module at the repository root, with the canonical module path resolved through go.mod Source: go.mod:1-10. All Go user-facing binaries, including the encore CLI, are organized under cli/cmd/, which follows the conventional Go layout where each subdirectory holds a main package for a distinct executable Source: cli/cmd/encore/main.go:1-30. The Rust side is declared through Cargo.toml at the repository root, indicating at least one Rust crate is built and linked into the delivered tooling Source: Cargo.toml:1-20. This split lets performance-sensitive parsing, build orchestration, or bundling tasks be implemented in Rust while keeping the bulk of the framework and CLI surface area in Go.

The high-level separation of responsibilities implied by the layout is summarized below.

Source: go.mod:1-10, cli/cmd/encore/main.go:1-30, Cargo.toml:1-20.

CLI Architecture

The encore binary is the developer-facing entry point for nearly every workflow: creating a new app, running locally, generating code, parsing declarative infrastructure definitions, and producing builds for deployment. The main package is intentionally thin: it delegates immediately to the root command defined in cli/cmd/encore/root/rootcmd.go, which configures the command tree, global flags, and subcommands Source: cli/cmd/encore/main.go:1-30, Source: cli/cmd/encore/root/rootcmd.go:1-60. From there, each subcommand (for example, run, build, test, version) is implemented in its own package under cli/cmd/encore/ and wired into the root command via standard Go-style command registration.

This command-tree shape is what allows the same binary to host both interactive developer workflows (local run, watch, trace) and non-interactive ones (CI builds, version checks, upgrades). The root command is also where global configuration such as logging verbosity, working directory resolution, and the path to the on-disk Encore installation is established before any subcommand executes Source: cli/cmd/encore/root/rootcmd.go:1-80. Because the same CLI is shipped both as a developer tool and as the build/deploy agent used in pipelines, this single entry point must remain stable across environments.

flowchart TD
    A["encore binary (main.go)"] --> B["root command (rootcmd.go)"]
    B --> C["run / build / test / version subcommands"]
    B --> D["Global flags & config"]
    C --> E["Go runtime & parser packages"]
    C --> F["Rust crates (Cargo.toml)"]
    E --> G["User application source"]
    F --> G
    G --> H["Local dev or deployment artifact"]

Integration Considerations & Community Topics

Several recurring community discussions map directly onto the architectural seams visible in the repository. Monorepo and project-layout questions, such as support for Turborepo-managed monorepos or custom ignore files like .encoreignore, surface as CLI-side configuration rather than runtime changes: the root command and underlying build pipeline must learn to discover the correct application root and exclude unintended paths Source: cli/cmd/encore/root/rootcmd.go:1-80. Feature requests for additional API styles (for example, gRPC generation) require new parsing and code-generation passes inside the Go-side framework and corresponding generators wired through the CLI build pipeline. Type-system and ORM interoperability requests, such as support for typeof inferSelect patterns from query builders, are a function of how the Go runtime exposes generated types back to user code. Security-sensitive changes, such as those that prompted the v1.57.11 advisory, span both the CLI distribution and the deployed runtime, which is why the project treats a CLI version bump and a runtime redeploy as a single coordinated remediation step.

Together, these patterns show that Encore's architecture intentionally centralizes orchestration in the Go CLI while delegating low-level systems work to Rust, giving the project room to extend both the developer surface and the supported deployment targets without rewriting the command tree.

Related Pages

Related topics: Parser & Code Generation Pipeline, Runtime, CLI & Deployment, Encore Overview & System Architecture

SDK Primitives & Resource Declarations

Purpose and Scope

Encore's SDK exposes a small, opinionated set of primitives that let application code declare infrastructure-shaped resources directly within the source tree. Rather than writing separate configuration files, the developer calls a constructor function (for example sqldb.NewDatabase, pubsub.NewTopic, objects.NewBucket, cache.NewCluster, or cron.NewJob) and binds the resulting object to a package-level variable. Encore's build tooling then scans the source code, picks up these declarations, and provisions the corresponding backend resources (PostgreSQL database, Pub/Sub topic, object storage bucket, Redis-backed cache, scheduled job, etc.). Source: runtimes/go/storage/sqldb/db.go:1-40, runtimes/go/pubsub/topic.go:1-40.

The same model is reused for the TypeScript runtime, where corresponding modules under runtimes/js/encore.dev/... expose equivalent factories such as SQLDatabase so that TS applications can declare resources in the same declarative style. Source: runtimes/js/encore.dev/storage/sqldb/mod.ts:1-60.

In other words, a primitive is the in-code declaration of an infrastructure resource, and the runtime package is the file the build system parses to discover it.

The Declaration Pattern

Although each primitive has a domain-specific configuration struct (database name and driver options, topic name and delivery guarantees, bucket name, cache cluster nodes, cron schedule), they all share a common shape:

1. A domain struct (e.g., *sqldb.Database, *pubsub.Topic[*datastore.T], *objects.Bucket, *cache.Cluster, *cron.Job).
2. A New* constructor that returns both the usable handle and an error.
3. A package-level var that holds the singleton instance, which Encore scopes to the package.
4. A //encore:api or //encore:service annotation that tells the tooling how the resource relates to service surface area. Source: runtimes/go/storage/sqldb/db.go:60-120, runtimes/go/cron/cron.go:40-90.

This pattern is what enables static analysis: the variable declaration is the unit of discovery, and the constructor's arguments fully describe the desired resource.

// illustrative
var (
    orders = sqldb.NewDatabase[models.Order]("orders", sqldb.DatabaseConfig{
        Migrations: migrate.NewStaticMigrations(...),
    })

    orderEvents = pubsub.NewTopic[*events.OrderEvent](pubsub.TopicConfig{
        Name:        "order-events",
        DeliveryGuarantee: pubsub.AtLeastOnce,
    })
)

Catalog of Core Primitives

The Go SDK currently ships the following declaration primitives, each living under its own runtime package:

The TypeScript SDK mirrors the database primitive through SQLDatabase, exposed from encore.dev/storage/sqldb. Source: runtimes/js/encore.dev/storage/sqldb/mod.ts:30-90.

Lifecycle, Discovery, and Operational Concerns

Once a primitive is declared, its lifecycle is driven by Encore's CLI and runtime manager:

• Discovery happens at parse time: the build tool walks each package, locates top-level variables initialized via New* calls, and extracts the configuration struct.
• Provisioning is then performed by the runtime manager, which creates the underlying cloud resource using the same name the developer used in code.
• Runtime usage is through the returned handle, which exposes typed methods such as db.Query, topic.Publish, bucket.Upload, cache.Get, or cron.Manager.Register. Source: runtimes/go/storage/sqldb/db.go:150-220, runtimes/go/storage/objects/bucket.go:120-200, runtimes/go/storage/cache/cache.go:130-210.

The New* constructors return the handle plus an error so the application can decide how to react when, for instance, the underlying connection pool fails to initialize. They are designed to be called once at package initialization time, which is why each resource is conventionally bound to a package-level var. Source: runtimes/go/pubsub/topic.go:130-180, runtimes/go/cron/cron.go:140-190.

A practical implication is that runtime services depend on the same declared resources for both local development and deployed environments. Local runs spin up embedded equivalents (for example, a local PostgreSQL for sqldb.NewDatabase), while the cloud deployment manager contacts the cloud provider using the declared configuration. This is what allows a single source of truth — the code itself — to drive environment behavior across development, preview, and production.

Limitations and Roadmap Notes from the Community

Several long-running community discussions map directly onto this primitives layer:

• gRPC APIs (Issue #9): the primitive layer today only declares infra-shaped resources; exposing user-facing RPC contracts via a new primitive (parallel to pubsub.NewTopic) has been requested so that typed, code-generated clients can be produced the same way messaging and storage clients are today.
• Monorepo support (Issue #1681): structuring multiple Encore applications within a Turborepo/pnpm monorepo requires each app subtree to keep its primitive declarations isolated so the CLI's discovery pass does not mix resources across apps.
• Object Storage proposal (Issue #410): the objects.NewBucket primitive already covers blob storage, and the proposal explores how richer static-asset hosting can layer on the same declaration.
• Inferring row types (Issue #1669): for sqldb.NewDatabase[T], the inferred row type currently must be writable from the user's source; the discussion tracks expanded inference support so that read-only shapes (such as typeof inferSelect) can also be passed.
• .encoreignore (Issue #1723): gives developers explicit control over which directories the discovery scan treats as source, which indirectly governs where primitive declarations are recognized.

Summary

Encore's SDK primitives are deliberately few but composable: one constructor per resource kind, declared at the package level, and consumed through a typed handle. Each primitive maps to a runtime package (Go) or module (TypeScript), and each becomes the unit of static discovery, provisioning, and operation. The design reduces infrastructure to in-code declarations that are portable across local and cloud environments, while leaving the door open for further primitive types — gRPC, richer object-storage tiers, and broader monorepo support being the most actively requested additions.

Related Pages

Related topics: SDK Primitives & Resource Declarations, Runtime, CLI & Deployment, Encore Overview & System Architecture

Parser & Code Generation Pipeline

Encore's Parser & Code Generation Pipeline is the foundation that transforms user-written application source code into a complete application model, language-agnostic schema, and downstream artifacts such as API clients, server stubs, and service bindings. It exists in two parallel language tracks — a Go pipeline rooted in v2/parser/parser.go and a TypeScript pipeline rooted in tsparser/src/parser/mod.rs — both feeding into the same code-generation layer (v2/codegen/gen.go). Together they allow Encore to introspect a program statically without executing it and then synthesize the additional code a runtime or external client needs.

Purpose and Scope

The pipeline performs three duties:

1. Static analysis of source files to extract services, RPC/API endpoints, structs, interfaces, databases, and other declarations without running the program.
2. Type resolution to fully evaluate generic types, mapped/underlying types, and cross-file references so the rest of the toolchain can rely on a resolved type graph.
3. Code generation that emits supplementary sources (service clients, server entry points, marshalling code) that integrate with the user's hand-written code.

Because the parser never executes user code, it depends on package metadata, AST inspection, and type-checker hooks. Source: v2/parser/parser.go:1-80.

Go Parser (`v2/parser`)

The Go parser is constructed via NewParser and walks the package using the golang.org/x/tools/go/packages loader plus the go/ast and go/types standard packages. It produces a Package value that holds files, declarations, services, and resolved type information.

Key responsibilities include:

• Loading the user's application module and recording each file, import, and declaration. Source: v2/parser/parser.go:80-160.
• Resolving service and RPC definitions declared via Encore framework functions and binding them to their implementing Go functions. Source: v2/parser/parser.go:160-260.
• Computing schema-level type information so that downstream codegen can emit transport-layer types (e.g. HTTP/JSON request and response shapes).

The parser uses the Go type checker to resolve generic instantiations, type aliases, and embedded fields. This allows code generators to ask "what is the underlying request struct for endpoint X?" and receive a fully concrete type. Source: v2/parser/parser.go:260-360.

TypeScript Parser (`tsparser`)

The TypeScript side is implemented in Rust using the swc JavaScript/TypeScript frontend. tsparser/src/parser/mod.rs exposes the top-level entry points that walk modules, identify Encore-specific decorators and call expressions, and produce a Module description analogous to the Go Package.

TypeScript's structural type system makes type resolution more involved than in Go. tsparser/src/parser/types/type_resolve.rs implements utilities that follow type aliases, mapped types, conditional types, and template literal types until they reach a concrete shape. This module is essential for users that lean on helpers such as Drizzle's typeof table.$inferSelect, where the actual row type is hidden behind a chain of generic aliases. Source: tsparser/src/parser/types/type_resolve.rs:1-120.

The parser emits an intermediate representation (IR) describing endpoints, payloads, and resource bindings. This IR is consumed by the code generators in v2/codegen. Source: tsparser/src/parser/mod.rs:1-150.

Code Generation Layer (`v2/codegen`)

The codegen pipeline is orchestrated by v2/codegen/gen.go, which selects and runs generators based on the parsed application model. Generators are independent units; each receives the parsed IR and emits files into a build directory.

The orchestrator is responsible for dependency ordering: schema generation must complete before client generation so the latter can reference the former's output. It also writes generator outputs to a per-build directory so they can be compiled alongside user code. Source: v2/codegen/gen.go:80-220.

apigen/maingen is particularly important because it produces the actual main package that imports each declared service and binds it to the HTTP/gRPC transport. Without it, an Encore application would have no entry point. Source: v2/codegen/apigen/maingen/maingen.go:1-160.

Pipeline Workflow

The end-to-end flow can be summarized as:

1. The CLI invokes the parser appropriate to the application's language.
2. The parser walks source files, resolves types, and produces the application model.
3. gen.go runs ordered generators that consume the model and write derived sources.
4. The build system compiles user code together with the generated sources into a runnable artifact.

This architecture keeps user-facing code minimal: developers declare endpoints and resources in idiomatic Go or TypeScript, and the pipeline synthesizes everything required to expose and consume them. Community interest in features such as gRPC codegen (issue #9) is addressed by adding additional generators alongside apigen rather than changing the parser, illustrating the extensibility of this design. Likewise, support for advanced type constructs like typeof inferSelect (issue #1669) is a matter of improving the type-resolution layer in tsparser so the IR exposes concrete row types.

Extensibility and Limits

Because parsing and generation are decoupled, new transport targets (gRPC, Webhooks, Object Storage handlers referenced in issue #410) can be added as independent generators. The parser only needs to surface the declarations; codegen decides how to materialize them. Source: v2/codegen/gen.go:1-80.

The pipeline assumes source files are well-formed and that all referenced types are statically resolvable. Types created at runtime (e.g. via reflection or dynamic evaluation) cannot appear in the IR and therefore cannot participate in generated artifacts — a constraint worth noting when integrating libraries that rely on heavy metaprogramming.

Related Pages

Related topics: SDK Primitives & Resource Declarations, Parser & Code Generation Pipeline, Encore Overview & System Architecture

Runtime, CLI & Deployment

Encore is distributed as a single Go binary, encore, that orchestrates the entire developer experience: parsing the user's application source, compiling it, running it locally, supervising databases, exposing a developer dashboard, and producing deployable artifacts. The CLI follows a client/daemon model so that long-lived services (SQL proxy, dashboard, MCP server) survive between command invocations.

CLI Entry Point and Daemon Architecture

Every user-facing subcommand is implemented under cli/cmd/encore/ and is rooted in run.go, which defines the top-level Run function that all commands dispatch through. The CLI delegates nearly all work to a long-running daemon process so that expensive setup (compiler cache, traced logs, database connections) is amortized across many encore run, encore test, and encore db invocations.

The daemon lives in cli/daemon/daemon.go and exposes a gRPC API used by the CLI. It owns subsystems for:

• Process supervision (run) — starting, restarting, and tracing the user's compiled binary.
• Local SQL database management (sqldb) — provisioning Postgres/Postgres-compatible databases via Docker.
• The Developer Dashboard (dash) — a local web UI for inspecting traces, logs, and APIs.
• An MCP server (mcp) for editor integration.
• Secret and configuration storage.
• Build and codegen pipelines.

When the CLI starts, it first checks whether a daemon is already running; if not, it spawns one in the background and connects over a Unix socket. This keeps subsequent invocations nearly instant and lets editors stream trace data continuously.

Local Runtime and `encore run`

The encore run command compiles the user's application using a custom Go build pipeline that injects Encore's runtime hooks and then supervises the resulting binary. The supervisor is implemented in cli/daemon/run/run.go, which handles process lifecycle, log forwarding, trace correlation, and graceful shutdown on Ctrl+C.

Encore's compile pipeline parses each Go file, registers every encore.dev/... annotation (services, APIs, Pub/Sub topics, databases, cron jobs, etc.), and emits strongly typed client code as part of the build. The runtime inside the user's binary then exposes:

• An HTTP server for declared API endpoints.
• gRPC infrastructure (server-side; client gRPC for user APIs is requested in #9).
• A Pub/Sub message bus.
• Database connection pooling to the locally proxied databases.
• Tracing and structured logging that streams to the daemon.

The result is a single static binary that mirrors how the app will behave in production, which is critical because local and deployed environments share the same runtime contract.

Local Databases, Dashboard, and MCP

Database provisioning is handled by cli/daemon/sqldb/manager.go, which boots containerized PostgreSQL instances per database declared in the application and exposes them through a connection proxy on a stable local port. Applications connect using a URL that the daemon transparently rewrites, so each developer's environment mirrors production without manual configuration.

The Developer Dashboard is implemented in cli/daemon/dash/dash.go. It is an embedded web app served by the daemon that displays service graphs, request traces, log streams, API explorers, and database explorers. Because the daemon owns the tracing pipeline, traces from encore run appear in the dashboard live.

The MCP server in cli/daemon/mcp/mcp.go exposes the same machine-readable project model to editors such as Cursor and Claude Code, allowing AI assistants to query service metadata, generate code, and run Encore commands directly.

Build, Deploy, and Monorepo Considerations

For deployment, the CLI uses the same compile pipeline that powers encore run to produce an OCI-compatible container image. The daemon resolves the full dependency graph across services, embeds infrastructure descriptors (service definitions, database schemas, API schemas) alongside the binary, and uploads the artifact to the target environment — either Encore Cloud or a self-hosted Kubernetes cluster via the open-source encoredev/encore runtime images.

Monorepo support is a frequent community concern (see #1681). Encore expects a single Encore application root per workspace; sub-packages outside that root are not treated as Encore services. Users running pnpm/Turborepo workspaces typically invoke the Encore CLI inside one sub-package while keeping frontend code in siblings. The requested .encoreignore directive (#1723) would let users explicitly exclude non-Encode paths from trace and parse scans, which is especially useful when the Encore root sits inside a larger monorepo.

A high-level view of the architecture:

flowchart LR
  User[Developer] --> CLI[encore CLI]
  CLI --> Daemon[Encore Daemon<br/>gRPC over Unix socket]
  Daemon --> Build[Compile + Codegen Pipeline]
  Daemon --> Run[Process Supervisor<br/>run.go]
  Daemon --> SQL[SQL DB Manager<br/>manager.go]
  Daemon --> Dash[Dashboard<br/>dash.go]
  Daemon --> MCP[MCP Server<br/>mcp.go]
  Run --> App[User Application Binary]
  SQL --> Docker[(Docker: Postgres)]
  App -. traces/logs .-> Daemon
  Daemon -. deploy artifact .-> Cloud[Encore Cloud / Self-host]

Security patches are delivered through the same CLI channel: encore version update pulls and verifies new daemon binaries, and v1.57.11 included remediations that required re-deployment of self-hosted applications. This makes the daemon both the local control plane and the trusted source for build and deploy operations.

Doramagic Pitfall Log

Found 10 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2515

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2495

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2461

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/encoredev/encore

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/encoredev/encore

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/encoredev/encore

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2493

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using encore with real data or production workflows.

• Encore.ts: api.raw delivers no client-disconnect signal — response 'clos - github / github_issue
• Deploy branch selection UI shows deleted branches - github / github_issue
• Docs: self-host infra config databases map key and name descriptions - github / github_issue
• encore version exits 1 when the update-check hangs - github / github_issue
• [[SECURITY ADVISORY] v1.57.11](https://github.com/encoredev/encore/releases/tag/v1.57.11) - github / github_release
• v1.57.10 — Fixes and improvements - github / github_release
• v1.57.9 — Fixes and improvements - github / github_release
• v1.57.8 — Fixes and improvements - github / github_release
• v1.57.6 — Fixes and improvements - github / github_release
• v1.57.5 — Improvements and bug fixes - github / github_release
• v1.57.4 — Update to go1.26.3 - github / github_release
• v1.57.3 — Fixes and improvements - github / github_release