bug: /api/v1/* routes return 404 — v1Router is defined but never mounted in Express app

[Uchechukwu-Ekezie]

Description

The README and API documentation state that /api/v1/ is the canonical API namespace and /api/ is the legacy namespace scheduled for deprecation. However, v1Router is imported but never mounted in backend/src/index.ts. All /api/v1/* requests return 404 Route not found.

Steps to Reproduce

# Start the backend
npm run dev --prefix backend

# Try the documented canonical endpoint
curl http://localhost:3001/api/v1/portfolio/GABC...
# Returns: {"success": false, "error": "Route not found"}  ✗

# The legacy endpoint works fine
curl http://localhost:3001/api/portfolio/GABC...
# Returns: {"success": true, "portfolio": {...}}  ✓

Root Cause

backend/src/api/v1Router.ts (entire file):

import { Router } from 'express'
import { portfolioRouter } from './routes'

const v1Router = Router()
v1Router.use('/', portfolioRouter)

export { v1Router }

backend/src/index.ts:

import { portfolioRouter } from './api/routes'
// v1Router is NOT imported

app.use('/api', portfolioRouter)   // ← Legacy namespace mounted ✓
app.use('/', portfolioRouter)      // ← Root namespace mounted
// app.use('/api/v1', v1Router)    ← This line is missing ✗

v1Router exists as a module but is never imported or registered with the Express app.

README Documentation (Contradicts Actual Behavior)

From README.md (~line 170):

Canonical API namespace: /api/v1/*
Legacy compatibility namespace (deprecated, temporary): /api/*

This is the opposite of reality — /api/* works and /api/v1/* does not.

Impact

1. Any client or integration built against /api/v1/ (as the README instructs) receives 404 for every request
2. The documented deprecation path is inverted — the "legacy" namespace is the only one that functions
3. There is no migration path for consumers to upgrade to v1, because v1 doesn't exist

Proposed Fix

Option A (Recommended): Mount v1Router in index.ts

// backend/src/index.ts
import { portfolioRouter } from './api/routes'
import { v1Router } from './api/v1Router'

// Mount canonical v1 namespace
app.use('/api/v1', v1Router)

// Mount legacy namespace with deprecation header middleware
app.use('/api', legacyApiDeprecation, portfolioRouter)

This makes both namespaces functional and allows a real deprecation timeline for /api/*.

Option B: Remove v1Router and update documentation

If versioned routing is not planned, delete v1Router.ts, remove references to /api/v1/ from all documentation, and update README to reflect that /api/ is the current and only namespace.

Verify the fix

curl http://localhost:3001/api/v1/portfolio/GABC...
# Should return: {"success": true, "portfolio": {...}}

Files Affected

• backend/src/index.ts — add app.use('/api/v1', v1Router) import and mount
• backend/src/api/v1Router.ts — no change needed (already correct)
• README.md — update or remove /api/v1/ references until fix is deployed
• docs/API.md — clarify which namespace is currently active

[LawalRahman]

Hi,

I’m a full-stack and blockchain developer with experience building fintech and payment-focused applications. I work across frontend, backend, APIs, and smart contract integrations with a strong focus on turning ideas into working products quickly.

For this issue, I’d focus on delivering a simple but well-structured solution that demonstrates clear Stellar utility rather than unnecessary complexity. My priority would be reliability, clean architecture, secure implementation, and an MVP that can realistically evolve beyond the hackathon.

I’m ready to begin immediately and ship iteratively with clear progress updates.

[Marvy247]

I've reviewed the issue description, and I'm confident I can implement all the requested details smoothly.​Please assign this issue to me! I can have a PR ready for review in a few hours. Thank You.

[bbjiggy]

Hi, I'd like to work on this issue,

I came across this issue and would love to take it on. It seems there is a mismatch between the documentation and the actual implementation where the /api/v1/ canonical namespace is failing with a 404 because v1Router is imported but never explicitly mounted in backend/src/index.ts.

Why I'm a Good Fit
I have strong experience working with TypeScript/Node.js backends and Express routing architectures. I'm comfortable navigating codebase initializations, debugging routing middleware, and ensuring correct route mounting without breaking existing legacy endpoints.

High-Level Plan
Locate & Mount: Verify where v1Router is imported in backend/src/index.ts and mount it under the /api/v1 path.

Preserve Legacy: Ensure the existing /api/ legacy router remains intact so current clients experience zero downtime.

Validate: Write/run integration tests using a tool like Supertest (or the repository's preferred testing framework) to ensure /api/v1/* endpoints now respond with 200/201 instead of 404.

Please assign this to me if the approach looks good, and I'll submit a PR shortly!

[Uchechukwu-Ekezie]

Hi @bbjiggy, thanks for showing interest in this task and for applying.

I’ve gone through your approach and I really like how you structured it—it’s clear and well thought out. Looking forward to seeing your contribution on this.

[bbjiggy]

Thank you. I am ready to get this done within the next 36 hours

[grantfox-oss]

🦊 GrantFox — @bbjiggy has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #9)
2. Your PR will be reviewed by the grantFoxin maintainers

Good luck! Track your progress on GrantFox.