# https://github.com/encoredev/encore Project Manual

Generated at: 2026-07-18 08:03:06 UTC

## Table of Contents

- [Encore Overview & System Architecture](#page-overview)
- [SDK Primitives & Resource Declarations](#page-primitives)
- [Parser & Code Generation Pipeline](#page-parser)
- [Runtime, CLI & Deployment](#page-runtime)

<a id='page-overview'></a>

## Encore Overview & System Architecture

### Related Pages

Related topics: [SDK Primitives & Resource Declarations](#page-primitives), [Parser & Code Generation Pipeline](#page-parser), [Runtime, CLI & Deployment](#page-runtime)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/encoredev/encore/blob/main/README.md)
- [cli/cmd/encore/main.go](https://github.com/encoredev/encore/blob/main/cli/cmd/encore/main.go)
- [cli/cmd/encore/root/rootcmd.go](https://github.com/encoredev/encore/blob/main/cli/cmd/encore/root/rootcmd.go)
- [Cargo.toml](https://github.com/encoredev/encore/blob/main/Cargo.toml)
- [go.mod](https://github.com/encoredev/encore/blob/main/go.mod)
</details>

# 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.

| Component | Location | Language | Role |
|-----------|----------|----------|------|
| CLI entry point | `cli/cmd/encore/main.go` | Go | Process bootstrap for the `encore` binary |
| Root command | `cli/cmd/encore/root/rootcmd.go` | Go | Top-level CLI command tree, flags, and dispatch |
| Go module / runtime | `go.mod`, runtime packages | Go | Framework runtime, parsing, code generation |
| Rust components | `Cargo.toml`, `rust/` crates | Rust | Systems-level tooling linked into CLI or daemons |

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.

```mermaid
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.

---

<a id='page-primitives'></a>

## SDK Primitives & Resource Declarations

### Related Pages

Related topics: [Parser & Code Generation Pipeline](#page-parser), [Runtime, CLI & Deployment](#page-runtime), [Encore Overview & System Architecture](#page-overview)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [runtimes/go/storage/sqldb/db.go](https://github.com/encoredev/encore/blob/main/runtimes/go/storage/sqldb/db.go)
- [runtimes/go/pubsub/topic.go](https://github.com/encoredev/encore/blob/main/runtimes/go/pubsub/topic.go)
- [runtimes/go/storage/objects/bucket.go](https://github.com/encoredev/encore/blob/main/runtimes/go/storage/objects/bucket.go)
- [runtimes/go/storage/cache/cache.go](https://github.com/encoredev/encore/blob/main/runtimes/go/storage/cache/cache.go)
- [runtimes/go/cron/cron.go](https://github.com/encoredev/encore/blob/main/runtimes/go/cron/cron.go)
- [runtimes/js/encore.dev/storage/sqldb/mod.ts](https://github.com/encoredev/encore/blob/main/runtimes/js/encore.dev/storage/sqldb/mod.ts)
</details>

# 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.

```go
// 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:

| Primitive | Package | Constructor | Role |
| --- | --- | --- | --- |
| SQL Database | `encore.dev/storage/sqldb` | `NewDatabase[T]` | Provisioned PostgreSQL with migrations `Source: [runtimes/go/storage/sqldb/db.go:80-150]()` |
| Pub/Sub Topic | `encore.dev/pubsub` | `NewTopic[T]` | Strongly-typed async messaging `Source: [runtimes/go/pubsub/topic.go:60-130]()` |
| Object Bucket | `encore.dev/storage/objects` | `NewBucket` | Blob/object storage `Source: [runtimes/go/storage/objects/bucket.go:40-110]()` |
| Cache Cluster | `encore.dev/storage/cache` | `NewCluster` | Key/value cache (e.g., Redis) `Source: [runtimes/go/storage/cache/cache.go:50-120]()` |
| Cron Job | `encore.dev/cron` | `NewJob` | Scheduled invocation `Source: [runtimes/go/cron/cron.go:70-140]()` |

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.

---

<a id='page-parser'></a>

## Parser & Code Generation Pipeline

### Related Pages

Related topics: [SDK Primitives & Resource Declarations](#page-primitives), [Runtime, CLI & Deployment](#page-runtime), [Encore Overview & System Architecture](#page-overview)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [v2/parser/parser.go](https://github.com/encoredev/encore/blob/main/v2/parser/parser.go)
- [v2/codegen/gen.go](https://github.com/encoredev/encore/blob/main/v2/codegen/gen.go)
- [v2/codegen/apigen/apigen.go](https://github.com/encoredev/encore/blob/main/v2/codegen/apigen/apigen.go)
- [v2/codegen/apigen/maingen/maingen.go](https://github.com/encoredev/encore/blob/main/v2/codegen/apigen/maingen/maingen.go)
- [tsparser/src/parser/mod.rs](https://github.com/encoredev/encore/blob/main/tsparser/src/parser/mod.rs)
- [tsparser/src/parser/types/type_resolve.rs](https://github.com/encoredev/encore/blob/main/tsparser/src/parser/types/type_resolve.rs)
</details>

# 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.

| Generator | Purpose | Source |
|-----------|---------|--------|
| `apigen` | Produces per-service API descriptions (HTTP routes, request/response schemas) used by both server and client tooling. | [v2/codegen/apigen/apigen.go:1-120]() |
| `apigen/maingen` | Generates the language-agnostic `mastermains` entry points that wire declared services into a runnable binary. | [v2/codegen/apigen/maingen/maingen.go:1-160]() |
| language clients | Emit SDK stubs (Go/TS/JS) for each service endpoint, derived from the same schema. | [v2/codegen/gen.go:80-220]() |

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.

---

<a id='page-runtime'></a>

## Runtime, CLI & Deployment

### Related Pages

Related topics: [SDK Primitives & Resource Declarations](#page-primitives), [Parser & Code Generation Pipeline](#page-parser), [Encore Overview & System Architecture](#page-overview)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [cli/cmd/encore/run.go](https://github.com/encoredev/encore/blob/main/cli/cmd/encore/run.go)
- [cli/daemon/daemon.go](https://github.com/encoredev/encore/blob/main/cli/daemon/daemon.go)
- [cli/daemon/run/run.go](https://github.com/encoredev/encore/blob/main/cli/daemon/run/run.go)
- [cli/daemon/sqldb/manager.go](https://github.com/encoredev/encore/blob/main/cli/daemon/sqldb/manager.go)
- [cli/daemon/dash/dash.go](https://github.com/encoredev/encore/blob/main/cli/daemon/dash/dash.go)
- [cli/daemon/mcp/mcp.go](https://github.com/encoredev/encore/blob/main/cli/daemon/mcp/mcp.go)
</details>

# 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`](https://github.com/encoredev/encore/blob/main/cli/cmd/encore/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`](https://github.com/encoredev/encore/blob/main/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`](https://github.com/encoredev/encore/blob/main/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](https://github.com/encoredev/encore/issues/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`](https://github.com/encoredev/encore/blob/main/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`](https://github.com/encoredev/encore/blob/main/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`](https://github.com/encoredev/encore/blob/main/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](https://github.com/encoredev/encore/issues/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](https://github.com/encoredev/encore/issues/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:

```mermaid
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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: encoredev/encore

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2515

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2495

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2461

## 4. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/encoredev/encore

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/encoredev/encore

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/encoredev/encore

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2493

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore

<!-- canonical_name: encoredev/encore; human_manual_source: deepwiki_human_wiki -->