PLAN: Magic e-VERSE Codebase Current State & Priorities

Executive Summary

This plan is based on direct inspection of the current Magic-e-VERSE repository at:

/home/adminmichiel1/Magic-e-VERSE

It is intentionally a codebase plan, not a full infrastructure plan. The goal is to document what is actually present in the repository now, what is clearly working in source, where the boundaries are weak, and what should be prioritized next.

Short version

The repository contains substantial real product value, but it is not a unified monorepo and it is not one coherent system boundary.

It is best understood as three adjacent applications:

a heavily customized Medusa backend
a customized Next.js storefront
a separate React/Vite portal frontend

The current state is:

feature-rich
business-specific
operationally ambitious
security-weak in key places
thinly tested
loosely bounded between systems

Scope And Evidence

This plan was built from direct inspection of:

repository structure
package manifests
route inventories
selected implementation files
SQL table usage across the backend
current git status and recent commit history

Audit constraints

no root workspace manifest exists for the repo
dependencies were not installed in the Magic-e-VERSE repo during the audit
no full runtime validation of backend or storefront behavior was performed from this snapshot
the portal frontend references APIs that are not present in this repository, so part of the platform exists outside the audited codebase

Repository Index

Top-level structure

Path	Role	Current interpretation
`backend/`	Medusa backend	primary business logic center
`storefront/`	Next.js storefront	customer-facing commerce frontend
`magic_beta_portal/`	React/Vite portal	internal frontend backed by another API service
`migrations/`	SQL migrations	very small migration footprint

Important structural finding

There is no root package.json, no workspace file, and no monorepo orchestration at repo root. This is three app folders living in one git repository.

Size snapshot

Metric	Value
tracked files in repo	~8049
`backend/src` files	139
`storefront/src` files	267
`magic_beta_portal/src` files	45
meaningful automated test files found	1 backend health spec

Current State By Application

1. Backend

Stack

From backend/package.json:

Medusa 2.11.3
TypeScript
PostgreSQL access via pg
PDF generation via pdfkit
custom supplier integration tooling
Medusa admin customization

What the backend has become

This is no longer a starter Medusa server. It is acting as:

commerce backend
B2B operations backend
quotation, order, and invoice engine
CMS and content backend
supplier sync and orchestration backend
branding and sales-channel provisioning backend
developer operations backend

Major custom surfaces

Observed backend custom areas include:

admin APIs for quotations, orders, invoices, customers, categories, suppliers, technique pricing, payment terms, settings, and versioning
admin UI extensions inside Medusa
store CMS APIs
store access gating and access requests
store APLT product and category APIs
mega menu APIs
customer logo and logo-configuration APIs
supplier connector sync APIs
brand wizard APIs
dev-project APIs that operate on git, files, and docker

Database-backed domains observed in code

Commerce and import domain

aplt_products
aplt_stock
aplt_categories
aplt_category_mappings
aplt_suppliers
aplt_techniques
aplt_technique_pricing
aplt_connector_sync

Commercial operations

aplt_customers
aplt_discount_groups
aplt_payment_terms
aplt_vat_codes
aplt_quotation_headers
aplt_quotation_lines
aplt_order_headers
aplt_order_lines
aplt_invoice_headers
aplt_invoice_lines
aplt_access_requests

Content and branding

aplt_brands
aplt_cms_pages
aplt_cms_settings
aplt_cms_footer_sections
aplt_cms_footer_links
aplt_cms_menus
aplt_cms_menu_items
aplt_cms_projects
aplt_cms_featured_products
aplt_cms_popular_categories

Developer and deployment operations

dev_projects
dev_project_files
dev_project_changelog
dev_project_deployments
dev_project_migrations
aplt_tenants
aplt_modules
aplt_tenant_modules
aplt_releases
aplt_deployment_logs

Architectural characteristics

Direct SQL is the dominant pattern

The backend relies heavily on route-local pg clients and inline SQL instead of central service abstractions.

That gives fast delivery, but it also means:

schema knowledge is scattered
authorization is route-local and inconsistent
testing is harder
refactoring cost is high

Medusa admin is deeply customized

The backend modifies the Medusa admin through:

custom admin routes under backend/src/admin/routes/*
injected branding and menu logic in backend/medusa-config.ts

This is powerful, but brittle. Some behavior depends on DOM mutation and route naming conventions rather than stable extension boundaries.

Connectors are a strong subsystem

backend/src/modules/connectors is one of the most developed parts of the codebase.

Observed supplier families:

Spranz
XD Connect
PF Concept
Mid Ocean
Toppoint

Observed sync types:

products
prices
stock
categories
print data

This is a meaningful platform subsystem, not glue code.

Backend strengths

substantial domain coverage for B2B commerce
supplier connectors are centrally organized
brand wizard shows clear product thinking around multi-brand provisioning
business workflows go well beyond generic cart and checkout
admin UI extension work is extensive and product-specific

Backend risks

Observed security and platform risks:

middleware disables protections for several custom route groups
many routes explicitly set AUTHENTICATE = false
admin/dev-projects/* is broadly unauthenticated in code
/store/access-check fails open on backend error
shell execution is present in dev-project and connector flows
database and filesystem assumptions are environment-coupled

Backend current-state verdict

The backend is the strongest business asset in the repo and the biggest source of operational risk.

It is rich enough to power real business workflows, but it needs containment and cleanup more than it needs new breadth.

2. Storefront

Stack

From storefront/package.json:

Next.js 15.3.6
React 19 RC
Tailwind CSS
Medusa JS SDK
custom API routes and direct database access

What the storefront does today

This is not a stock Medusa storefront. It contains:

custom CMS consumption
custom product and category browsing behavior
multi-language support
domain-based brand switching
custom PIM pricing reads
access request and access gate experience
Magic Logo product configuration flows

Storefront architecture characteristics

Hybrid data model

The storefront uses:

Medusa APIs
custom backend APIs
direct PostgreSQL reads through local API routes
local hardcoded brand config

That makes it flexible, but it also creates duplicated truth sources.

Brand model mismatch

The backend clearly treats brand as database-backed configuration:

aplt_brands
brand wizard
sales channel and publishable key provisioning

The storefront still treats brand mostly as code:

hardcoded DEFAULT_BRANDS
hardcoded domains
TODOs to fetch brand config later

This is one of the clearest architectural mismatches in the platform.

Magic Logo is a first-class product feature

The storefront contains significant custom logic for logo workflows:

supplier-specific SKU parsing
technique lookup
iframe and modal designer flow
cart metadata integration
logo-specific local state and storage handoff

This is clearly a differentiated product area, not incidental customization.

Storefront strengths

broad custom business functionality already present
clear module breakdown
custom pricing, CMS, brand, and logo flows are integrated into customer-facing UX
Next App Router structure is modern enough for long-term use

Storefront risks

Observed quality risks:

ignoreDuringBuilds: true
ignoreBuildErrors: true
React 19 RC in production app code
reactStrictMode: false
debug logging throughout runtime paths
mixed dependency strategy with some latest Medusa packages

Storefront current-state verdict

The storefront is more mature functionally than procedurally.

It likely delivers business value today, but the team has traded away build trust to keep moving quickly.

3. Magic Beta Portal

Stack

From magic_beta_portal/package.json:

Vite
React 19
React Router
Tailwind v4
markdown and Mermaid rendering

What the portal frontend contains

The portal UI already covers:

login, 2FA, and forced password change states
documentation browser
project pages
support screens
tenant and infrastructure pages
developer reference pages
leads
admin user management

Critical boundary finding

The portal frontend exists in this repo, but the backend it talks to does not.

Evidence from the code:

API base is /api
Vite proxy points /api to http://localhost:4096
expected routes include docs, auth, releases, support, admin, projects, ecommerce files, and more

Those APIs are not implemented in this repository.

Current-state verdict

The portal frontend is real and actively developed, but it is only partially auditable from this repo. The system boundary is split across repositories or services.

Cross-Cutting Assessment

What the codebase is really optimized for

The codebase is optimized for:

fast feature delivery
business-specific workflows
direct control over data and operations
pragmatic customization over framework purity

It is not currently optimized for:

strict separation of concerns
low-risk scaling of contributors
strong automated verification
clean portability across environments

Testing reality

Observed test surface is extremely thin.

Meaningful automated coverage found:

one backend health check spec

Not meaningfully covered in source:

connectors
quotation flows
order flows
invoice generation
brand wizard
access gating
Magic Logo flows
storefront critical paths
portal behavior

Environment coupling

The code assumes a specific runtime environment:

specific PostgreSQL database names
host.docker.internal
local and host docker reachability
hardcoded external filesystem paths
local service ports and tenant slot conventions

This is workable for the current operator environment, but not yet a cleanly portable platform.

Current State Scorecard

Area	Score	Notes
Product depth	8/10	substantial custom business logic
Feature breadth	8/10	portal, commerce, CMS, connectors, ops
Architectural cohesion	4/10	useful systems, weak boundaries
Security posture	3/10	serious auth and ops-surface concerns
Test coverage	1/10	essentially absent
Build trust	3/10	storefront explicitly ignores errors
Maintainability	4/10	speed optimized, not boundary optimized
Business value density	8/10	lots of real domain logic already present

Priority Roadmap

Priority 0: Secure the dangerous surfaces

This is the first block of work.

lock down the entire admin/dev-projects route family
review every route currently marked AUTHENTICATE = false
revisit middleware bypasses for custom route groups
change access checks from fail-open to safer behavior
review shell-execution paths and filesystem access boundaries

Reason:

operational control plane capabilities exist inside the app layer
the blast radius is too high if perimeter protections fail

Priority 1: Restore trustworthy build and release signals

re-enable TypeScript build failures in storefront
re-enable ESLint build failures in storefront
standardize dependency pinning strategy
add CI for install, lint, typecheck, and smoke tests

Reason:

without trusted gates, every deployment carries hidden risk

Priority 2: Define system ownership and boundaries

document exactly which app owns which domain
document which portal APIs live outside this repo
identify where direct SQL is strategic and where it should be extracted
define authoritative sources of truth for brands, tenants, releases, and docs

Reason:

the repo currently behaves like multiple systems sharing one git tree

Priority 3: Unify the brand model

move storefront brand resolution to backend-backed brand data
stop treating brand metadata as hardcoded app config
define the relationship between brand, tenant, sales channel, and domain clearly

Reason:

the platform clearly wants multi-brand support, but the implementation is split-brain

Priority 4: Stabilize core business subsystems

connector synchronization
quotation, order, and invoice workflows
CMS and brand provisioning
Magic Logo integration

Reason:

these are high-value differentiators and deserve stronger internal abstractions

Priority 5: Add real coverage where failure hurts the business most

Start with:

quotation creation and confirmation
order creation and status transitions
invoice generation
connector sync happy and failure paths
brand wizard provisioning
storefront add-to-cart and checkout
Magic Logo cart and configuration flow

Reason:

the goal is not blanket coverage first
the goal is confidence around revenue and operations paths

Quick Wins

add a root README to the Magic-e-VERSE repo explaining the 3-app structure
document required environment variables per app
remove hardcoded frontend publishable-key assumptions where possible
cut noisy production console.log output
document the portal backend as an external dependency

Final Verdict

The current Magic e-VERSE codebase is already a serious product platform. It is not lacking capability.

The main engineering need now is control:

control over security
control over boundaries
control over build trust
control over operational complexity

If those are addressed next, the existing customization work becomes a strong long-term foundation instead of an accumulating risk surface.