Overview

Maze Legacy is an npm-workspaces TypeScript monorepo. Current source and image definitions contain three runnable applications—React UI, NestJS Core API, and NestJS Git service—backed by PostgreSQL and several external APIs. Deployment definitions conflict: Helm and Travis include all three applications, while the direct Terraform application map includes only UI and Core. The live topology therefore requires runtime confirmation. Most business capabilities are modules inside Maze Core rather than separately deployed microservices.

Container classification

The classifications below apply the canonical Container, Component, and Deployable unit definitions. Architecture retains the repository evidence for each classification; reusable definitions live in Glossary.

Element	Classification	Why
Maze UI	Container — deployable application	Own image build, NGINX runtime, Helm Deployment/Service and port 4200.
Maze Core	Container — deployable application	Own image build, NestJS process, Helm Deployment/Service and port 8080.
Maze Git	Container — deployable application candidate	Own image build, NestJS process, Helm Deployment/Service and port 8082; omitted from direct Terraform, so live deployment is unconfirmed.
PostgreSQL	Container — independently provisioned data store	Separate Aurora/RDS infrastructure resource; a local database image also exists.
packages/api, packages/shared, packages/logger, provider packages, controllers and services	Components/libraries	They are packaged into UI, Core, or Git and have no independent runtime/deployment boundary in the current source.

loading...

Request and data flow

1. The browser downloads the React/Vite single-page application from Maze UI's NGINX container.
2. UI services call same-origin /api/ routes and send a Maze bearer token; Git operations use /api/git/ and also pass a GitHub token.
3. The Helm Ingress definition routes / to Maze UI, /api to Maze Core, and the more specific /api/git path to Maze Git; the direct Terraform application map does not establish Maze Git's deployment.
4. Maze Core validates identity and authorization, runs domain workflows, reads and writes PostgreSQL through Prisma, and invokes cloud, object-storage, email, OIDC, Prism, and Git endpoints.
5. Maze Git performs GitHub OAuth and repository lifecycle operations including clone, branch, commit, pull request, tag, and release operations.
6. Terraform/import workflows use local process execution and provider-specific packages; generated files may be committed to GitHub or GitHub Enterprise.

Maze Core component map

CoreModule composes 26 controllers and their services into one runtime. The component groups below are logical code components, not separate network containers.

Component group	Responsibilities	Representative API surfaces
Identity and access	Local/W3/GitHub authentication, JWTs, password reset, users, roles, members, cloud credentials, administration.	/api/auth, /api/user, /api/super, /api/cloud-accounts
Project and canvas	Projects, memberships, resources, canvas state, templates, variables, tidy/format behavior, activity feed.	/api/projects, /api/maze, /api/project-templates, /api/variables/:projectId, /api/tidy, /api/activity
Infrastructure lifecycle	Import cloud resources, generate HCL, validate/plan/apply/destroy Terraform, CLI workflows, machine images.	/api/imports, /api/terraform, /api/cli, /api/machines
Cost and insight	Cost estimation/history, cloud insight data, service status.	/api/cost, /api/status, insight controller routes
Integration and publication	Prism import/publish/auth, Git operations, images/object storage, email, notifications/SSE.	/api/prism, /api/git, /api/images, /api/sse
Feedback and operations	Feedback, bug reports, crash reports, messages, release/config administration.	/api/feedback, /api/bug-reports, /api/crashReport

Build and deployment

Layer	Observed implementation
Source/build	npm workspaces; TypeScript; Vite for UI; tsc for NestJS applications; Prisma client generation and migrations.
Images	Separate Dockerfiles build ui, maze, and maze-git; cloud/tooling images also exist for provider and Terraform work.
Registry	Image scripts reference AWS ECR (170700933973.dkr.ecr.eu-west-2.amazonaws.com); current Dockerfiles also reference IBM Container Registry base images (de.icr.io).
Runtime	Helm creates Deployments, ClusterIP Services, optional HPAs, and one NGINX Ingress. Values define UI:4200, Core:8080, and Git:8082.
Infrastructure	Terraform artifacts provision AWS VPC/EKS/RDS/Route53 and install ingress-nginx, cert-manager, Argo CD, metrics-server, and optional Tekton/GitLab tooling.
Persistence	Prisma targets PostgreSQL through DATABASE_URL; infrastructure code declares RDS while local tooling also supplies a containerized database.

Architectural characteristics

• Modular monolith plus specialist service: business logic is concentrated in Maze Core; Git is separately deployable but Git controller/service code also exists inside the Core package.
• Shared source and release coupling: UI imports API controller types; Core and Git depend on shared workspace packages. Container builds copy broad monorepo sections.
• Synchronous integrations: HTTP and SDK calls dominate. Server-Sent Events provide notifications, but no durable message broker is evident.
• Stateful workflow execution: imports, generated files, temporary credentials, Terraform working directories, and Git clones use local filesystem paths in addition to PostgreSQL/object storage.

Material drift and risks

Critical credential exposure

The analyzed commit contains live-looking secrets or private material: a tracked TLS private key, a Firebase service-account private key, plaintext database connection credentials, an embedded Infracost API key, a Slack webhook, and committed binary Terraform plan files that may contain sensitive values. This documentation intentionally does not reproduce any values.

Treat all affected credentials as compromised until proven otherwise: revoke and rotate them, audit use, remove sensitive objects from Git history, invalidate exposed plan artifacts, and add automated secret scanning. Evidence locations include nginx/nginx-selfsigned.key, packages/api/lib/maze-multicloud-firebase.json, packages/api/lib/apiDefaults.ts, packages/api/services/CostService.ts, .releaserc.yaml, and tooling/maze-deployment/environments/*/*.tfplan.

1. Topology drift: Compose lists more than 20 services, many mapped to missing scripts/workspaces; Helm lists three applications, while direct Terraform lists two. Operational documentation must not treat any one repository topology as confirmed production truth without runtime evidence.
2. Route overlap: Maze Core registers a Git controller while Maze Git exposes a second Git controller. Ingress path precedence determines which implementation receives /api/git traffic.
3. Security defaults: source contains fallback session/JWT secrets and local database credentials. Production safety depends on complete environment injection.
4. Credential concentration: Maze Core handles user, Git, cloud, object-storage, email, and Terraform credentials and can execute infrastructure tools.
5. Sensitive configuration placement: Terraform derives a credential-bearing DATABASE_URL and writes it into a Kubernetes ConfigMap rather than a Secret.
6. Ephemeral filesystem coupling: clone/import/Terraform workflows rely on local directories without persistent-volume declarations in the Helm template.
7. Deployment-template defects: the Helm template has suspicious replica and CronJob constructs, and no resource requests/limits, probes, pod security context, or network policies are visible.
8. Stateful single-process behavior: Express sessions and SSE subscribers use in-memory state, which fragments across replicas and is lost on restart.
9. Limited automated assurance: root/API test commands can succeed without running tests; the observed Travis definition does not enforce the declared test/analysis stages.
10. Version/platform inconsistency: build environments use different Node versions and mutable base-image tags; registry and deployment mechanisms also conflict.

Source basis

Primary evidence: root package.json; applications/maze-core; applications/maze-git; applications/ui; packages/api; packages/thirdparty; tooling/helm-chart; tooling/docker; tooling/maze-deployment; nginx/nginx.conf. Snapshot: maze-legacy/maze@03522c898990b0794c2526ef942aa6dd3c32b27a.