Screens Organization

Overview

This document defines how screens (full-page views tied to routes) are organized in the Lantern app, separate from reusable components.

Directory Structure

All screens live in src/screens/ and are organized by domain:

src/screens/
  auth/           # Authentication & onboarding screens
  dashboard/      # Main dashboard views
  merchant/       # Merchant-specific screens
  profile/        # User profile management screens

Screens vs Components

What is a Screen?

A screen is a full-page view that:

• Is tied to a specific route (hash route in our case)
• Manages page-level state and data fetching
• Composes multiple components to create a complete view
• Represents a distinct user-facing page in the application

What is a Component?

A component is a reusable UI element that:

• Can be used across multiple screens
• Encapsulates specific functionality or UI patterns
• Should be independently testable and documented
• Lives in src/components/

Current Screen Routes

Route	Screen Component	Location	Domain
#/	Dashboard	src/screens/dashboard/Dashboard.jsx	dashboard
#/signup	SignupFlow	src/screens/auth/SignupFlow.jsx	auth
#/profile	ProfileSettings	src/screens/profile/ProfileSettings.jsx	profile
#/onboarding/profile	CreateNewProfile	src/screens/profile/CreateNewProfile.jsx	profile
#/merchant	MerchantDashboard	src/screens/merchant/MerchantDashboard.jsx	merchant
#/merchant/new	OfferForm	src/screens/merchant/OfferForm.jsx	merchant

Adding New Screens

When creating a new screen:

1. Determine the domain: Is it auth, dashboard, merchant, profile, or a new domain?
2. Create in the appropriate directory: Place the screen file in src/screens/{domain}/
3. Follow naming conventions: Use PascalCase for the file name (e.g., NewScreen.jsx)
4. Add route in App.jsx: Register the hash route and import the screen
5. Create stories: Add a Storybook story file alongside the screen (e.g., NewScreen.stories.jsx)
6. Update this document: Add the new route to the table above

Example: Adding a Settings Screen

// 1. Create src/screens/profile/Settings.jsx
export default function Settings() {
  return <div>Settings content</div>
}

// 2. Add to src/App.jsx
import Settings from './screens/profile/Settings'

// In the routing logic:
{route === '#/settings' && <Settings />}

// 3. Create src/screens/profile/Settings.stories.jsx
import Settings from './Settings'
export default { title: 'Screens/Profile/Settings', component: Settings }
export const Default = () => <Settings />

// 4. Update this document with the new route

Domain Guidelines

Auth Domain (src/screens/auth/)

• User authentication flows
• Signup, login, password reset
• Onboarding screens (first-time user experience)

Dashboard Domain (src/screens/dashboard/)

• Main application views
• Home/landing screens after login
• Primary user interfaces
• Internal dashboard screens (used by Dashboard.jsx):
  • PlacesScreen.jsx (wraps HomeView)
  • VenueDetailScreen.jsx (wraps VenueView)
  • ActiveLanternScreen.jsx (wraps ActiveLanternView)
  • LanternSuccessScreen.jsx (success state wrapper)

Merchant Domain (src/screens/merchant/)

• Merchant-specific functionality
• Offer management
• Merchant analytics and dashboards

Profile Domain (src/screens/profile/)

• User profile management
• Settings and preferences
• Account management

Best Practices

1. Keep screens focused: Each screen should have a single, clear purpose
2. Extract reusable logic: If logic is used across multiple screens, move it to src/lib/ or a custom hook
3. Compose with components: Build screens by composing smaller, reusable components from src/components/
4. Co-locate stories: Keep Storybook stories next to the screen file for easy discovery
5. Test screens: Add tests for critical user flows in src/__tests__/
6. Document routes: Always update the route table in this document when adding new screens

Migration Notes

On January 4, 2026, we migrated from a mixed structure to the unified src/screens/ organization:

• Before: Screens were scattered across src/components/, src/dashboard/, and src/merchant/
• After: All screens consolidated in src/screens/{domain}/
• Rationale: Clear separation of concerns, better developer experience, improved scalability

Related Documentation

• Component Organization
• Scaffold Documentation
• Sitemap