lightweight
05-glimpse.md

Instructions for Adding Duplicate Routes (Multiple Paths to Same Handler)

This guide covers how to properly create multiple URL paths that serve the same functionality while maintaining clean architecture.

Use Case

When you need both /views/feature/:id and /feature/:id to work identically, serving the same handler with the same authentication and behavior.

❌ Common Mistakes to Avoid

1. Direct Controller Import in Main Router

Create val
// DON'T DO THIS - violates architectural separation
import { featureHandler } from "./backend/controllers/feature.controller.ts";
app.get("/feature/:id", featureHandler);

2. Mounting Routes at Wrong Path

Create val
// DON'T DO THIS - creates /feature/feature/:id instead of /feature/:id
app.route("/feature", viewRoutes); // where viewRoutes has app.get("/feature/:id", ...)

3. Forgetting Authentication Middleware

Create val
// DON'T DO THIS - inconsistent auth between routes
app.use("/views/*", authCheck);
// Missing: app.use("/feature/*", authCheck);
app.route("/feature", featureRoutes);

✅ Correct Implementation Steps

Step 1: Analyze Existing Route Structure

First, understand the current route setup:

# Check existing routes file
cat /backend/routes/views/_views.routes.ts

# Check main router setup
cat /main.tsx

Look for:

  • How the route is currently defined (e.g., app.get("/feature/:id", handler))
  • What authentication middleware is applied
  • How routes are mounted in main.tsx

Step 2: Create Dedicated Route Module

Create a new route module that mirrors the existing functionality:

Create val
// Create /backend/routes/feature/_feature.routes.ts
import { Hono } from "npm:hono@3.12.12";
import { featureHandler } from "../../controllers/feature.controller.ts";

const app = new Hono();

// Use /:id (not /feature/:id) since it will be mounted at /feature
app.get("/:id", featureHandler);

export default app;

Key Points:

  • Route path is /:id not /feature/:id (mounting handles the prefix)
  • Import the same controller used by the original route
  • Follow the same naming convention (_feature.routes.ts)

Step 3: Add Route Documentation

Create val
// Create /backend/routes/feature/README.md
# Feature Routes

This directory contains routes for the feature functionality.

## Routes

### GET /:id

- **Purpose**: [Copy purpose from original route docs]
- **Authentication**: Required (Google OAuth)
- **Parameters**: `id` - [Parameter description]
- **Response**: [Response description]

This is the same functionality as `/views/feature/:id` but mounted at `/feature/:id` for convenience.

Step 4: Update Main Router

Add the new route module to main.tsx:

Create val
// Add import
import featureRoutes from "./backend/routes/feature/_feature.routes.ts";

// Add authentication middleware (same as original)
app.use("/feature/*", authCheck);

// Mount routes
app.route("/feature", featureRoutes);

Critical Order:

  1. Import route modules (not controllers)
  2. Apply authentication middleware
  3. Mount routes after middleware

Step 5: Verify Route Mounting Logic

Ensure you understand the path composition:

Main router mount: app.route("/feature", featureRoutes)
Route definition: app.get("/:id", handler)
Final URL: /feature/:id ✅

NOT:
Route definition: app.get("/feature/:id", handler)
Final URL: /feature/feature/:id ❌

Step 6: Test Both Routes

Test that both routes work identically:

# Test original route
curl /views/feature/test-id

# Test new route
curl /feature/test-id

# Both should return identical responses (login page if not authenticated)

Complete Example Implementation

File Structure

backend/routes/
├── views/_views.routes.ts          # Original route
├── feature/
│   ├── _feature.routes.ts          # New duplicate route
│   └── README.md                   # Documentation

main.tsx

Create val
import { Hono } from "npm:hono@3.12.12";
import { lastlogin } from "https://esm.town/v/stevekrouse/lastlogin_safe";

// Import route modules (NOT controllers)
import viewRoutes from "./backend/routes/views/_views.routes.ts";
import featureRoutes from "./backend/routes/feature/_feature.routes.ts";
import authCheck from "./backend/routes/authCheck.ts";

const app = new Hono();

// Apply authentication to both routes
app.use("/views/*", authCheck);
app.use("/feature/*", authCheck);

// Mount routes
app.route("/views", viewRoutes);
app.route("/feature", featureRoutes);

export default lastlogin(app.fetch);

_feature.routes.ts

Create val
import { Hono } from "npm:hono@3.12.12";
import { featureHandler } from "../../controllers/feature.controller.ts";

const app = new Hono();

app.get("/:id", featureHandler);

export default app;

Architecture Principles

✅ Maintain Clean Separation

  • Main router → Route modules → Controllers → Services
  • Never import controllers directly in main router
  • Each route module handles one logical grouping

✅ Consistent Authentication

  • Apply same middleware to both route paths
  • Ensure identical security behavior
  • Document authentication requirements

✅ DRY Principle

  • Reuse existing controllers and services
  • Don't duplicate business logic
  • Share the same handler implementation

Testing Checklist

  • Both routes return identical responses
  • Authentication works the same on both routes
  • No 404 errors on either route
  • Route parameters are correctly extracted
  • Error handling is consistent
  • Documentation is updated

Troubleshooting

Route Returns 404

  • Check route mounting path vs route definition path
  • Verify authentication middleware is applied before route mounting
  • Ensure route module exports default app

Different Behavior Between Routes

  • Verify both routes use the same controller
  • Check that authentication middleware is applied to both
  • Confirm route parameters are extracted identically

Architecture Violations

  • Never import controllers in main router
  • Always go through route modules
  • Maintain consistent file naming conventions

This approach ensures clean, maintainable code while providing the flexibility of multiple URL paths for the same functionality.

Instructions for Adding Duplicate Route with Dashboard Table Display

Overview

Create a duplicate route that serves the same functionality as an existing route, then update the dashboard to display both routes in a clean comparison table format.

Step 1: Analyze Existing Route Structure

  1. Check main router (/main.tsx) to understand current routing setup
  2. Identify the existing route in /backend/routes/views/_views.routes.ts
  3. Locate the controller that handles the route functionality
  4. Note the authentication middleware applied to the existing route

Step 2: Create Duplicate Route Module

  1. Create directory structure: /backend/routes/glimpse/
  2. Create route file: /backend/routes/glimpse/_glimpse.routes.ts
    • Import Hono and the existing controller
    • Define route as /:id (not /glimpse/:id since mounting handles prefix)
    • Export the Hono app as default
  3. Create documentation: /backend/routes/glimpse/README.md
    • Document the route purpose, authentication, parameters, and response
    • Note that it's equivalent to the original route

Step 3: Update Main Router

  1. Add import for the new route module in /main.tsx
  2. Add authentication middleware for the new route path (same as original)
  3. Mount the route after middleware setup
  4. Maintain proper order: imports → middleware → route mounting

Step 4: Update Dashboard Display

  1. Locate the dashboard file at /backend/routes/views/dashboard.tsx
  2. Find the section that displays glimpse links (look for demo pages display)
  3. Replace the existing link display with a three-column table:
    • Column 1: "Name" (30% width) - shows page title with emoji
    • Column 2: "Original Route" (35% width) - shows /views/glimpse/{:id} as clickable link
    • Column 3: "New Shortcut Route" (35% width) - shows /glimpse/{:id} as clickable link
  4. Style the table with:
    • Clean borders and spacing
    • Header row with background color
    • Different link colors (blue for original, green for new)
    • Monospace font for route paths
    • Proper vertical alignment

Step 5: Implementation Details

Route File Template (_glimpse.routes.ts):

import { Hono } from "npm:hono@3.12.12";
import { glimpseHandler } from "../../controllers/glimpse.controller.ts";

const app = new Hono();
app.get("/:id", glimpseHandler);
export default app;

Main Router Updates:

  • Import: import glimpseRoutes from "./backend/routes/glimpse/_glimpse.routes.ts";
  • Auth: app.use("/glimpse/*", authCheck);
  • Mount: app.route("/glimpse", glimpseRoutes);

Dashboard Table Structure:

  • Three columns with clear headers
  • Page name in first column (no repetition)
  • Both route formats as clickable links
  • Consistent styling and spacing
  • Color coding for route types

Step 6: Testing

  1. Test both routes return identical responses (login page if not authenticated)
  2. Verify table display shows all demo pages with both route formats
  3. Confirm links work and open in new tabs
  4. Check responsive layout and readability

Key Principles

  • No code duplication - reuse existing controller
  • Consistent authentication - same middleware for both routes
  • Clean architecture - maintain separation between router, routes, and controllers
  • User-friendly display - clear comparison table without repetition
  • Functional testing - both routes must behave identically

This approach creates a clean duplicate route with an intuitive dashboard display that demonstrates both URL formats side-by-side.

Townie, stop here! Before proceeding to additional steps, confirm that this step is working correctly.

If everything is working as intended: conclude this step with these messages:

  1. Briefly summarize the work that was just completed and why it's important
  2. Provide the URL to the dashboard that you just updated so the user can see that the new routes are live. Tell the user that they can copy and paste that URL into a new tab to see the links.

Next step: build a task endpoint that saves /glimpse/:id routes to Notion database pages

Follow the instructions in /_townie/07-save.md to add the /tasks/url endpoint