On this page

Application Design#

DevStride is written in TypeScript from end to end: the backend, the web app, the infrastructure definitions and the internal tooling. Everything lives in one repository.

The repository#

The repository is a pnpm workspace with these parts:

Part What it is
backend The API and every background consumer, run as AWS Lambda functions
frontend The Vue 3 web app and the customer portal
packages/mcp The Model Context Protocol (MCP) server that lets AI assistants work in DevStride
stacks The infrastructure definitions (SST version 2 on AWS CDK)
cli ds, the internal engineering and operations command-line tool
infra Supporting infrastructure: CI runners, deploy identities, event topology

Backend#

Runtime. Node.js 22 on AWS Lambda (arm64), with the Hono web framework. Every request and response is described with Zod schemas, and those schemas also produce the public OpenAPI document.

Architecture. The backend follows domain-driven design with command and query separation (CQRS):

  • Commands and queries. Every operation is either a command, which changes something, or a query, which reads something. Each is sent through a command bus or a query bus to the one handler that owns it.
  • Entities and repositories. Business rules live on domain entities. Storage sits behind repository interfaces, so the rules do not depend on the database.
  • Errors as values. Handlers return a success or failure result rather than throwing, so every caller has to deal with failure.
  • Dependency injection. Each command and query registers what it needs, which keeps handlers small and easy to test.

Events. When an entity changes, it records a domain event. After the change is saved, those become integration events that other modules can listen to:

  • Ordinary integration events go through Amazon EventBridge. They are delivered at least once and in no fixed order.
  • Ordered integration events go through an SNS FIFO topic into SQS FIFO queues. They are delivered in order within a group, for work such as hierarchy moves and rollup recalculation.
  • Events are saved before they are sent. A job re-sends any that were saved but not delivered, so an event is not lost if a send fails.

Module boundaries. A module never imports another module's repository. To read another module's data it sends a query; to change it, a command; to react to it, it subscribes to an event. This is enforced in code review and keeps each module independently changeable.

The modules#

Area Modules
Work management Work items and workstreams, boards and cycles, roadmaps (Gantt), item templates, comments, approvals, time tracking, activity and notifications
Planning and insight Analytics (cycle time, throughput, progress, time allocation, exports)
Automation Automations (conditions, actions, schedules), background jobs, outbound webhooks
Customer-facing Service Desk (email and portal tickets, requesters and companies, SLAs, satisfaction surveys), Knowledge Base and documentation sites
AI The in-app AI assistant, documentation search, and public "Ask AI" answers on documentation sites
Organization and access Organizations and their configuration (custom fields, work types, estimates), users, teams and memberships, roles and permissions, authorization, authentication log, OAuth server
Integrations GitHub, Slack, Microsoft Teams, Azure DevOps, Jira and Formwork, importers, plugins, real-time (Pusher)
Billing Subscriptions, invoices and payments
Engineering operations Agent sessions, agent workflows and work claims (for AI coding agents), and an internal cloud-cost view, all staff only

Rollups#

Each work item and workstream stores totals rolled up from everything beneath it: counts by work type, estimates, effort, time spent, and the earliest and latest dates. These are recalculated in the database in the background whenever something underneath changes, then pushed to open browsers, so large hierarchies load quickly without adding them up on every read.

Web app#

Part Technology
Framework Vue 3 with the Composition API, Vue Router, Pinia for state
Components Quasar 2
Styling Tailwind CSS 3, with eight colour themes defined as CSS variables
Build Vite 6, type-checked with vue-tsc
Rich text TipTap 3 (ProseMirror)
Grids and charts A virtualized items table, a two-axis virtualized Gantt chart, AG Grid, Chart.js and d3
Real-time Pusher, on private channels for each organization and each user

The web app talks to the API through a client generated from the OpenAPI document, so the browser and the server always agree on request and response shapes.

Customer portal. The Service Desk portal is a separate, lightweight entry point in the same web app. It leaves out the heavy staff-side libraries, and its download size is held under a budget that the build checks.

Documentation sites. An organization's published Knowledge Base can be served as its own documentation site. Pages are built into static files, stored in S3 and served through CloudFront, with an optional "Ask AI" search box. This documentation is published that way.

API surfaces#

  • REST API. JSON over HTTPS under /v1, described by a public OpenAPI 3.1 document with an interactive reference.
  • Ways to authenticate. A signed-in user's session token; an API key and secret bound to one organization; or an OAuth 2.1 access token from DevStride's own authorization server. See Security and Identity.
  • MCP server. A hosted MCP server lets AI assistants such as Claude read and change work in DevStride. Its tools are generated from the same OpenAPI document as the API, so they cannot drift from it.
  • Outbound webhooks. Organizations can subscribe endpoints to events. Each delivery is signed, failed deliveries are retried, and any delivery can be replayed.
  • Inbound webhooks. GitHub, Jira, Azure DevOps, Stripe and Microsoft Teams send events to DevStride. Each source is verified before its event is acted on.
  • Plugins. Partner-built plugins, served by an external plugin service, can be switched on per organization and hidden per role.
Powered by DevStride