ts express ddd seed - Moses Yebei

The Problem

This repo is a seed project for experimenting with Domain-Driven Design (DDD) and related patterns in a TypeScript/Express stack. It solves the "how do I structure a Node.js API around domain logic rather than routes" problem, demonstrating a layered architecture with dependency injection, CQRS-style commands, and TypeORM persistence.

What This Does

ts-express-ddd-seed is a small Express API with two domain entities—Customer and Movie—each with its own application service, repository interface, and TypeORM-backed implementation. The code is organized into src/domain, src/application, src/infrastructure, and src/presentation folders, following the classic DDD layering.

Dependency injection is handled by src/ioc-container.ts using Inversify. The container wires the application services to their concrete TypeORM repositories, so the controllers in src/presentation/rest/ never touch persistence directly.

How It Is Wired

Execution starts at src/app.ts, which bootstraps the Express server and loads the IoC container. Requests hit the controllers (movie.controller.ts, customer-controller.ts), which delegate to application services (movie-store-application-service.ts, customer-application-service.ts). Those services call repository interfaces, resolved to typeorm-customer-repository.ts and typeorm-movie-repository.ts by the container.

The import graph shows 21 modules with 45 edges and no circular dependencies—clean layering. The hub is src/ioc-container (1 importer, 9 imports, instability 0.9), meaning it's the most volatile wiring point. The domain entities (src/domain/customer, src/domain/movie) have zero outgoing imports, which is correct for DDD—they're the stable core.

The call graph shows a straightforward flow: registerMovie and registerCustomer both call create, which routes through _repo (called from 5 places) to getRepo in typeorm-connection-service.ts. That's the only file that touches the database—3 functions read or write. rentMovie calls findById twice, then rentTo on the domain entity.

The file map: typeorm-customer-repository.ts owns customer persistence (4 functions), typeorm-movie-repository.ts owns movie persistence (7 functions, including list, update, delete), and typeorm-connection-service.ts manages the TypeORM connection. src/domain/movie.ts holds the rentTo domain logic—the one place business rules live outside the database layer.

How To Use It

git clone https://github.com/moses-y/ts-express-ddd-seed
cd ts-express-ddd-seed
npm install
npm start

Configuration lives in config/app-config.ts and ormconfig.json (TypeORM connection settings). The README documents npm run test:e2e:coverage for tests, npm run lint for TSLint, and npm run release to run all checks. No environment variables are documented; the app expects a local database per ormconfig.json.

Real-World Use

This fits as a starting template for a small service with a few bounded contexts. If you're building a rental system, the Movie.rentTo domain method is where you'd enforce business rules (e.g., "movie must be available"), while MovieStoreApplicationService.rentMovie orchestrates the transaction. The CQRS commands (RegisterMovieCommand, RentMovieCommand) show the pattern for separating write operations from reads.

Code Health & Issues

Static analysis found 8 issues: 4 high, 4 medium. The high-severity findings are:

High – No LICENSE file; all rights reserved by default, which blocks reuse in client work. Add MIT or Apache-2.0.
High – No lockfile; builds are non-reproducible. Commit the generated lockfile.
High – No CI pipeline; nothing runs the build or tests on changes. Add a workflow for push and pull_request.
High – No build gate for the Dockerfile; the image has never been validated automatically.

Medium findings: no Dependabot/Renovate, mutable Docker base image tag, no non-root USER in the Dockerfile, and a postinstall script in package.json that fetches a binary.

The repo has 2 e2e test files and no unit tests. No secrets were found.

The Bottom Line

This is a clean, well-layered DDD seed with no circular dependencies—a solid starting point for learning the pattern or scaffolding a small service. It's not production-ready: no CI, no lockfile, no license, and the Docker setup is incomplete. Use it as a reference for structure, not as a deployable baseline.

What the analyser found

Deployment readiness

4/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

34 files

TypeScript21
JSON8
Markdown1

ReactDocker

Module dependencies

The 10 most depended-upon modules of 21, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_domain_customer["customer"] n1_src_domain_movie["movie"] n2_src_utils_logger["logger"] n3_c_domain_customer_repository["customer-repository"] n4_m_typeorm_connection_service["typeorm-connection-servi"] n5_src_domain_movie_repository["movie-repository"] n6_ie_store_application_service["movie-store-application-"] n7_src_app["app"] n8_customer_application_service["customer-application-ser"] n9_mands_register_movie_command["register-movie-command"] n8_customer_application_service --> n3_c_domain_customer_repository n8_customer_application_service --> n0_src_domain_customer n9_mands_register_movie_command --> n1_src_domain_movie n6_ie_store_application_service --> n1_src_domain_movie n6_ie_store_application_service --> n9_mands_register_movie_command n6_ie_store_application_service --> n2_src_utils_logger n6_ie_store_application_service --> n5_src_domain_movie_repository n6_ie_store_application_service --> n0_src_domain_customer n6_ie_store_application_service --> n3_c_domain_customer_repository n3_c_domain_customer_repository --> n0_src_domain_customer n5_src_domain_movie_repository --> n1_src_domain_movie n1_src_domain_movie --> n0_src_domain_customer n4_m_typeorm_connection_service --> n2_src_utils_logger n4_m_typeorm_connection_service --> n1_src_domain_movie n4_m_typeorm_connection_service --> n0_src_domain_customer

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
MediumNo LICENSE file - unclear usage/redistribution rights root
LowDependencies declared without a lockfile - non-reproducible builds package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium4

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Commit a lockfile beside the manifesthigh

package.json

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Add a workflow that builds and tests this repositoryhigh

21 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

dockerfile/ubuntu (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Review the install lifecycle script and disable scripts in CImedium

package.json

postinstall

Install scripts are the execution vector for every npm compromise from event-stream onward, and a postinstall that fetches a binary makes the build depend on a URL nobody reviews.

Fix: Move the work into an explicit build step, or set ignore-scripts in CI and run it by name.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.