# momo300k/afridemeure architecture

> Architecture diagram of the GitHub repository momo300k/afridemeure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/momo300k/afridemeure
- Repository: https://github.com/momo300k/afridemeure

## Overview

1. **This is a multi-client monorepo centered on a Laravel API**
   The repository is not a single app. The core backend lives in `api/` and exposes the business capabilities for multiple frontends: a user web app (`web/`), a user mobile app (`mobile/`), and a partner mobile app (`mobile_partner/`). There is also an admin UI embedded in the Laravel backend via Filament.

2. **Backend architecture is domain-oriented, not controller-heavy**
   Under `api/app/Domains/`, the code is organized by business domain: Auth, Property, Booking, Lease, Payment, Messaging. Each domain has its own `Actions`, `DTOs`, `Events`, and often `Repositories`. That suggests the main flow is: controller/request → domain action → repository/model → event emission.

3. **Laravel controllers are thin entry points**
   `api/app/Http/Controllers/` contains controllers for each business area, plus webhook and Swagger endpoints. Validation is separated into `Http/Requests`, output shaping into `Http/Resources`, and access control into `Policies` and middleware. This keeps HTTP concerns at the edge while the domain layer owns the actual use cases.

4. **Persistence is relational and model-driven**
   The data layer is Eloquent-based, with models for users, properties, bookings, leases, payments, penalties, documents, conversations, messages, notifications, reviews, saved searches, and property images. Migrations show the system’s core data model is built around property lifecycle, reservation/lease lifecycle, and payment tracking.

5. **There is a clear business workflow around property → booking → lease → payment**
   The main operational flow appears to be:
   - properties are created/published/suspended,
   - users search and book properties,
   - bookings can be confirmed/cancelled,
   - leases are created/signed/renewed/terminated,
   - payments are initiated, received, failed, or penalized.
   Domain events such as `PropertyPublished`, `BookingConfirmed`, `LeaseSigned`, and `PaymentReceived` indicate the backend is event-aware and likely uses those events to trigger notifications or follow-up processing.

6. **Payments are a major subsystem with asynchronous processing**
   `api/app/Services/OrangeMoneyService.php` and `WaveService.php` show integration with external payment providers. Webhook handling is explicit (`WebhookController`, `ProcessPaymentWebhook` job, `ProcessWebhook` action). There are also penalty calculations and reminder flows (`CalculateDailyPenalties`, `SendPaymentReminder`, console commands for penalties/reminders), so payment timing and delinquency management are first-class concerns.

7. **Background jobs and console commands handle scheduled business rules**
   The backend includes queue jobs for payment webhook processing and reminders, plus artisan commands for calculating penalties and sending reminders. That means some business logic is intentionally decoupled from request/response cycles and runs asynchronously or on a schedule.

8. **Messaging, notifications, and documents are adjacent operational subsystems**
   Messaging has conversations and messages, with repositories and domain actions for creating conversations and sending messages. Notifications and documents exist as separate models/controllers/services, implying the system supports tenant/partner communication and lease/property document workflows alongside the core transaction flow.

9. **Admin operations are handled inside the backend with Filament**
   `api/app/Filament/` defines an internal admin panel with resources for users, properties, leases, payments, and penalties, plus dashboard stats. This is a separate operator-facing boundary from the public API and user apps, but it uses the same backend models and policies.

10. **The web frontend is a Next.js application for user-facing browsing and reservations**
    `web/` is a Next.js app with routes for home, authentication, search, property details, reservation flow, user space, partner space, and admin. It uses a small `lib/` layer for API access, auth context, and theme, plus reusable UI components. This app is the primary browser client for end users and partners.

11. **The mobile app is a Flutter client for tenants/users**
    `mobile/` follows a feature-first Flutter architecture with `data`, `domain`, `presentation`, and `usecases` per feature. It covers auth, property search, booking, lease viewing, messaging, favorites, profile, onboarding, and tenant space. The presence of a shared `api_service`, `auth_service`, storage, notifications, and deep links shows it is a remote API consumer with local session/state handling.

12. **The partner mobile app is a separate Flutter product with partner-specific capabilities**
    `mobile_partner/` mirrors the same Flutter layering, but the feature set is partner-centric: dashboard, listings management, tenant management, bookings confirmation, payments, leases, property detail, and messaging. This is a distinct client with its own auth/session flows and data views, not just a branded copy of the user app.

13. **There is also a shared Dart package layer for cross-app reuse**
    `packages/afridemeure_core` and `packages/afridemeure_ui` provide shared models, API/auth/storage services, and design system components/tokens. This indicates the Flutter apps are partially modularized so business entities and UI primitives can be reused rather than duplicated.

14. **Infrastructure and delivery are containerized and deployment-ready**
    The repo includes Dockerfiles for `api/` and `web/`, an `nginx/` configuration, `docker-compose.yml`, and a GitHub Actions workflow for deployment. That points to a container-based deployment model where Nginx likely fronts one or more app containers and the Laravel API serves as the central backend service.

15. **The `project/` and `design/` folders are design-handoff assets, not runtime code**
    The `project/` directory contains HTML/JS design prototypes and wireframes, while `design/` has component documentation. These files explain the intended UX and visual system, but they are separate from the production architecture. The `chats/` transcripts are there to preserve product intent from the design process.

Main entry points: [`api/app/Domains`](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains) (Domain layer), [`api/app/Http`](https://github.com/momo300k/afridemeure/tree/main/api/app/Http) (HTTP layer), [`api/app/Domains/Payment`](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Payment) (Payment), [`api/app/Models`](https://github.com/momo300k/afridemeure/tree/main/api/app/Models) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Laravel backend"]
  node_api_http["HTTP layer<br/>Laravel controllers"]
  node_api_domains["Domain layer<br/>Business actions"]
  node_api_property["Property<br/>Domain"]
  node_api_booking["Booking<br/>Domain"]
  node_api_lease["Lease<br/>Domain"]
  node_api_payment["Payment<br/>Domain"]
  node_api_messaging["Messaging<br/>Domain"]
  node_api_services["Services<br/>Integrations"]
  node_api_jobs["Jobs<br/>Async workers"]
  node_api_commands["Commands<br/>Scheduled tasks"]
  node_api_models[("Models")]
  node_api_filament["Admin panel<br/>Filament UI"]
end

subgraph group_clients["Client apps"]
  node_web_app["Web app<br/>Next.js frontend"]
  node_mobile_app["User mobile<br/>Flutter app"]
  node_partner_app["Partner mobile<br/>Flutter app"]
end

subgraph group_shared["Shared packages"]
  node_core_pkg["Core package<br/>Shared Dart package"]
  node_ui_pkg["UI package<br/>Shared Dart UI"]
end

subgraph group_delivery["Delivery"]
  node_delivery_cfg["Delivery stack<br/>Containers<br/>[docker-compose.yml]"]
end

subgraph group_design["Design assets"]
  node_design_assets["Design assets<br/>Handoff files"]
end

node_web_app -->|"API calls"| node_api_http
node_mobile_app -->|"API calls"| node_api_http
node_partner_app -->|"API calls"| node_api_http
node_api_http -->|"dispatches"| node_api_domains
node_api_domains -->|"includes"| node_api_property
node_api_domains -->|"includes"| node_api_booking
node_api_domains -->|"includes"| node_api_lease
node_api_domains -->|"includes"| node_api_payment
node_api_domains -->|"includes"| node_api_messaging
node_api_property -->|"reads/writes"| node_api_models
node_api_booking -->|"reads/writes"| node_api_models
node_api_lease -->|"reads/writes"| node_api_models
node_api_payment -->|"reads/writes"| node_api_models
node_api_messaging -->|"reads/writes"| node_api_models
node_api_payment -->|"integrates"| node_api_services
node_api_http -->|"admin edge"| node_api_filament
node_api_jobs -->|"processes"| node_api_payment
node_api_commands -->|"schedules"| node_api_payment
node_mobile_app -->|"reuses"| node_core_pkg
node_partner_app -->|"reuses"| node_core_pkg
node_mobile_app -->|"reuses"| node_ui_pkg
node_partner_app -->|"reuses"| node_ui_pkg
node_delivery_cfg -->|"deploys"| node_api_http
node_delivery_cfg -->|"deploys"| node_web_app
node_design_assets -.->|"informs"| node_web_app
node_design_assets -.->|"informs"| node_mobile_app
node_design_assets -.->|"informs"| node_partner_app

click node_api_http "https://github.com/momo300k/afridemeure/tree/main/api/app/Http"
click node_api_domains "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains"
click node_api_property "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Property"
click node_api_booking "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Booking"
click node_api_lease "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Lease"
click node_api_payment "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Payment"
click node_api_messaging "https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Messaging"
click node_api_services "https://github.com/momo300k/afridemeure/tree/main/api/app/Services"
click node_api_jobs "https://github.com/momo300k/afridemeure/tree/main/api/app/Jobs"
click node_api_commands "https://github.com/momo300k/afridemeure/tree/main/api/app/Console/Commands"
click node_api_models "https://github.com/momo300k/afridemeure/tree/main/api/app/Models"
click node_api_filament "https://github.com/momo300k/afridemeure/tree/main/api/app/Filament"
click node_web_app "https://github.com/momo300k/afridemeure/tree/main/web/app"
click node_mobile_app "https://github.com/momo300k/afridemeure/tree/main/mobile/lib"
click node_partner_app "https://github.com/momo300k/afridemeure/tree/main/mobile_partner/lib"
click node_core_pkg "https://github.com/momo300k/afridemeure/tree/main/packages/afridemeure_core/lib"
click node_ui_pkg "https://github.com/momo300k/afridemeure/tree/main/packages/afridemeure_ui/lib"
click node_delivery_cfg "https://github.com/momo300k/afridemeure/blob/main/docker-compose.yml"
click node_design_assets "https://github.com/momo300k/afridemeure/tree/main/project"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_http,node_api_domains,node_api_property,node_api_booking,node_api_lease,node_api_payment,node_api_messaging,node_api_services,node_api_jobs,node_api_commands,node_api_models,node_api_filament toneBlue
class node_web_app,node_mobile_app,node_partner_app toneAmber
class node_core_pkg,node_ui_pkg toneMint
class node_delivery_cfg toneRose
class node_design_assets toneIndigo
```

## Components

### Laravel backend

Core API, domain actions, jobs, services, and internal admin panel.

- [HTTP layer](https://github.com/momo300k/afridemeure/tree/main/api/app/Http): Laravel controllers · Thin request boundary with controllers, requests, resources, middleware, and policies. · `api/app/Http`
- [Domain layer](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains): Business actions · Domain-oriented use cases split by auth, property, booking, lease, messaging, and payment. · `api/app/Domains`
- [Property](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Property): Domain · Property creation, publishing, search, and suspension. · `api/app/Domains/Property`
- [Booking](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Booking): Domain · Booking creation and lifecycle confirmation/cancellation. · `api/app/Domains/Booking`
- [Lease](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Lease): Domain · Lease creation, signing, renewal, and termination. · `api/app/Domains/Lease`
- [Payment](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Payment): Domain · Payment initiation, webhook processing, penalties, and payment events. · `api/app/Domains/Payment`
- [Messaging](https://github.com/momo300k/afridemeure/tree/main/api/app/Domains/Messaging): Domain · Conversations and message sending for tenant and partner communication. · `api/app/Domains/Messaging`
- [Services](https://github.com/momo300k/afridemeure/tree/main/api/app/Services): Integrations · KYC, lease, notification, penalty, and payment-provider services. · `api/app/Services`
- [Jobs](https://github.com/momo300k/afridemeure/tree/main/api/app/Jobs): Async workers · Queued work for payment webhooks, reminders, and daily penalty calculation. · `api/app/Jobs`
- [Commands](https://github.com/momo300k/afridemeure/tree/main/api/app/Console/Commands): Scheduled tasks · Artisan commands for recurring penalty and reminder business rules. · `api/app/Console/Commands`
- [Models](https://github.com/momo300k/afridemeure/tree/main/api/app/Models): Eloquent models · Relational persistence for users, properties, bookings, leases, payments, conversations, messages, penalties, and related records. · `api/app/Models`
- [Admin panel](https://github.com/momo300k/afridemeure/tree/main/api/app/Filament): Filament UI · Operator-facing admin resources and dashboard embedded in Laravel. · `api/app/Filament`

### Client apps

User, partner, and mobile frontends that consume the backend API.

- [Web app](https://github.com/momo300k/afridemeure/tree/main/web/app): Next.js frontend · Browser client for browsing, searching, reserving, and partner/admin entry points. · `web/app`
- [User mobile](https://github.com/momo300k/afridemeure/tree/main/mobile/lib): Flutter app · Tenant-facing mobile client with feature-first architecture and local state/services. · `mobile/lib`
- [Partner mobile](https://github.com/momo300k/afridemeure/tree/main/mobile_partner/lib): Flutter app · Partner-facing mobile client for listings, tenants, bookings, leases, and payments. · `mobile_partner/lib`

### Shared packages

Cross-app Dart packages reused by the Flutter clients.

- [Core package](https://github.com/momo300k/afridemeure/tree/main/packages/afridemeure_core/lib): Shared Dart package · Reusable API, auth, storage, and model layer shared by Flutter apps. · `packages/afridemeure_core/lib`
- [UI package](https://github.com/momo300k/afridemeure/tree/main/packages/afridemeure_ui/lib): Shared Dart UI · Shared design system tokens and widgets for Flutter clients. · `packages/afridemeure_ui/lib`

### Delivery

Containerization and deployment configuration.

- [Delivery stack](https://github.com/momo300k/afridemeure/blob/main/docker-compose.yml): Containers · Docker, Nginx, Compose, and CI workflow for deployment. · `docker-compose.yml`

### Design assets

Handoff materials, prototypes, and wireframes kept outside runtime code.

- [Design assets](https://github.com/momo300k/afridemeure/tree/main/project): Handoff files · Prototypes, wireframes, and design documentation kept separate from runtime code. · `project`

## Connections

- Web app → HTTP layer: API calls · Next.js frontend consumes Laravel endpoints for browsing and reservation flows.
- User mobile → HTTP layer: API calls · Tenant mobile app talks to the backend through remote datasources and services.
- Partner mobile → HTTP layer: API calls · Partner mobile app uses the same backend API for operational workflows.
- HTTP layer → Domain layer: dispatches · Controllers and requests hand off to domain use cases.
- Domain layer → Property: includes · Property use cases are one major business boundary.
- Domain layer → Booking: includes · Booking flows are handled in a dedicated domain.
- Domain layer → Lease: includes · Lease lifecycle logic is isolated in its own domain.
- Domain layer → Payment: includes · Payments and penalties are modeled as a separate domain.
- Domain layer → Messaging: includes · Messaging is handled as a dedicated communication subsystem.
- Property → Models: reads/writes · Property actions persist through Eloquent models.
- Booking → Models: reads/writes · Booking actions persist and update relational records.
- Lease → Models: reads/writes · Lease actions operate on persisted lease and related entities.
- Payment → Models: reads/writes · Payments, penalties, and webhook state are stored in models.
- Messaging → Models: reads/writes · Conversations and messages are persisted through models.
- Payment → Services: integrates · Payment domain delegates to provider and penalty services.
- HTTP layer → Admin panel: admin edge · Admin-facing operations are embedded in the Laravel backend through Filament.
- Jobs → Payment: processes · Queued workers handle payment webhook processing and reminders.
- Commands → Payment: schedules · Console commands execute recurring penalty and reminder logic.
- User mobile → Core package: reuses · User mobile app shares models and API/auth/storage utilities.
- Partner mobile → Core package: reuses · Partner mobile app reuses shared core Dart logic.
- User mobile → UI package: reuses · User mobile app can use shared UI primitives and theme tokens.
- Partner mobile → UI package: reuses · Partner mobile app can use shared UI primitives and theme tokens.
- Delivery stack → HTTP layer: deploys · Container and web server configuration front the Laravel API.
- Delivery stack → Web app: deploys · Container and web server setup also supports the web frontend.
- Design assets → Web app: informs · Prototype and wireframe assets document the intended browser UI.
- Design assets → User mobile: informs · Handoff assets describe the intended mobile experience.
- Design assets → Partner mobile: informs · Handoff assets describe the partner product experience.
