Skip to Content
ConventionsAdding Features

Adding Features

A decision guide for engineers: where does your new feature live?

Decision Matrix

You’re building…Primary repoSupporting repoNotes
New student-facing featureHousr-AppHousr-API2Build API v2 module + App feature
New marketing/landing pageHousr-Webapp—Add page under src/app/[locale]/
New property search featureHousr-WebappHousr-API2May use direct DB queries for search
New admin capabilityHousr Portal—Add Filament resource or page
New agent/landlord featureHousr PortalHousr-API2Portal UI + optional API endpoints
New API endpointHousr-API2—Never add to API v1
New property data sourceHousr-Property-Feeds—New importer module
New payment featureHousr-API2Housr-App or WebappUse RyftPay

Step-by-Step: New App Feature

  1. Design the API: Create a new module in API v2 (Modules/YourFeature/) with routes, controllers, models, migrations
  2. Build the App feature: Create src/features/your-feature/ with api/, components/, hooks/, types/ subdirectories
  3. Wire up React Query: API function in api/, hook in hooks/, component consumes the hook
  4. Add navigation: Add tab or screen to src/app/ routing
  5. Handle regions: Check if the feature is UK-only, US-only, or both. Use feature flags if needed.

Step-by-Step: New Webapp Page

  1. Create the page: src/app/[locale]/your-page/page.tsx
  2. Add route config: Entry in src/components/layouts/route-config.tsx (controls header, hero, footer, CTA, allowed regions)
  3. Add navigation: Entry in src/components/layouts/navigation-config.ts if it should appear in the nav
  4. Add i18n: Entries in src/dictionaries/us.json and uk.json if region-specific text is needed
  5. Data fetching: Server Actions or direct API calls from the server component

Step-by-Step: New Portal Feature

  1. Create a Filament resource: php artisan make:filament-resource YourModel
  2. Define the table and form: Columns, filters, actions in the resource
  3. Add authorization: Define policies for who can view/create/edit/delete
  4. Add to navigation: Filament auto-registers resources, but you can customize grouping and ordering

Step-by-Step: New API v2 Module

  1. Create the module: php artisan module:make YourModule
  2. Define routes: Routes/api.php in the module
  3. Create models and migrations: Database/ directory in the module
  4. Build controllers: Follow RESTful conventions
  5. Add auth middleware: Use appropriate guards (Bearer JWT, Firebase, etc.)
  6. Test: Write feature tests for all endpoints

Common Patterns

Feature Flags

Use feature flags for gradual rollout:

  • App: FeatureFlagProvider context — check flags before rendering features
  • API v2: Config-based or database-driven flags
  • Portal: Filament can conditionally show/hide resources

Multi-Repo Features

Many features span multiple repos. The typical pattern:

  1. Start with the API (data model + endpoints)
  2. Build the consumer (App, Webapp, or Portal)
  3. Deploy API first, then consumer
  4. Use feature flags to decouple deployment timing
Last updated on
Git Workflow