# wolneydev/northloom-laravel architecture

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

- Interactive diagram: https://gitdiagram.com/wolneydev/northloom-laravel
- Repository: https://github.com/wolneydev/northloom-laravel

## Overview

Hospitable is a Laravel API for project planning, calendar tasks, project finances, reporting, and Telegram reminders, with REST and MCP interfaces over shared domain services. The main user workflow is an authenticated client or MCP tool requesting a project/task/financial action, which reaches domain logic and persistence; chat users can invoke MCP tools through the AI agent. The README documents these shared layers and capabilities. Source excerpts confirm selected controller, allocation, task-persistence, and dependency-binding behavior; other links are shown only where the README documents them.

Main entry points: [`app/Http/Controllers/Api`](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Http/Controllers/Api) (REST API), [`app/Mcp/Tools`](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Mcp/Tools) (MCP Server Tools), [`app/Infrastructure/Persistence/Eloquent`](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Infrastructure/Persistence/Eloquent) (Eloquent Repositories), [`app/Domain/Tasks/Services`](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Tasks/Services) (Task Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client Interfaces"]
  node_rest_api["REST API"]
  node_mcp_tools["MCP Server Tools"]
  node_mcp_server["MCP Server"]
end

subgraph group_domain["Domain Services"]
  node_project_service["Project Service"]
  node_task_service["Task Service"]
  node_financial_services["Financial Services"]
  node_report_service["Report Service<br/>[ReportService.php]"]
  node_user_service["User Service<br/>[UserService.php]"]
  node_creation_ideas["Creation Ideas"]
  node_report_output["Aggregated Reports<br/>[ReportService.php]"]
end

subgraph group_storage["Persistence"]
  node_eloquent_repositories["Eloquent Repositories"]
  node_domain_models["Domain Models"]
  node_database[("Database")]
  node_service_bindings["Service Bindings"]
end

subgraph group_messaging["Chat and Notifications"]
  node_conversation_service["Conversation Service"]
  node_chat_controller["Chat Controller<br/>[ChatController.php]"]
  node_chat_agent["Chat Agent"]
  node_task_notifications["Task Notifications"]
  node_telegram["Telegram Delivery"]
end

node_http_client(("HTTP Client"))
node_mcp_client(("MCP Client"))
node_chat_user(("Chat User"))

node_http_client -->|"calls"| node_rest_api
node_rest_api -->|"delegates to"| node_project_service
node_rest_api -->|"delegates to"| node_task_service
node_rest_api -->|"delegates to"| node_financial_services
node_rest_api -->|"requests reports"| node_report_service
node_rest_api -->|"manages users"| node_user_service
node_rest_api -->|"requests ideas"| node_creation_ideas
node_mcp_client -->|"connects via stdio"| node_mcp_server
node_mcp_server -->|"exposes tools"| node_mcp_tools
node_mcp_tools -->|"delegates to"| node_project_service
node_mcp_tools -->|"delegates to"| node_task_service
node_mcp_tools -->|"delegates to"| node_financial_services
node_mcp_tools -->|"requests reports"| node_report_service
node_mcp_tools -->|"suggests ideas"| node_creation_ideas
node_chat_user -->|"sends message"| node_chat_controller
node_chat_controller -->|"invokes agent"| node_chat_agent
node_chat_agent -->|"uses local MCP"| node_mcp_server
node_rest_api -->|"serves chat API"| node_chat_controller
node_task_service -.->|"schedules reminders"| node_task_notifications
node_task_notifications -->|"delivers via"| node_telegram
node_project_service -.->|"persists through"| node_eloquent_repositories
node_task_service -.->|"persists through"| node_eloquent_repositories
node_financial_services -.->|"persists through"| node_eloquent_repositories
node_eloquent_repositories -->|"queries and updates"| node_domain_models
node_domain_models -->|"stores records"| node_database
node_service_bindings -->|"binds implementations"| node_eloquent_repositories
node_service_bindings -->|"binds delivery"| node_telegram
node_report_service -->|"produces"| node_report_output

click node_rest_api "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Http/Controllers/Api"
click node_mcp_tools "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Mcp/Tools"
click node_mcp_server "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Mcp/Servers/HospitableServer.php"
click node_project_service "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Projects/Services"
click node_task_service "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Tasks/Services"
click node_financial_services "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Financials/Services"
click node_report_service "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Reports/Services/ReportService.php"
click node_user_service "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Users/Services/UserService.php"
click node_creation_ideas "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/CreationIdeas/Services"
click node_conversation_service "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Conversations/Services/ConversationService.php"
click node_chat_controller "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Http/Controllers/Api/ChatController.php"
click node_chat_agent "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Ai/Agents/HospitableChatAgent.php"
click node_task_notifications "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Tasks/Services/TaskNotificationService.php"
click node_telegram "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Infrastructure/Telegram/TelegramNotificationService.php"
click node_eloquent_repositories "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Infrastructure/Persistence/Eloquent"
click node_domain_models "https://github.com/wolneydev/northloom-laravel/tree/prod/app/Models"
click node_service_bindings "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Providers/AppServiceProvider.php"
click node_report_output "https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Reports/Services/ReportService.php"

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_rest_api,node_mcp_tools,node_mcp_server,node_http_client,node_mcp_client,node_chat_user toneBlue
class node_project_service,node_task_service,node_financial_services,node_report_service,node_user_service,node_creation_ideas,node_report_output toneAmber
class node_eloquent_repositories,node_domain_models,node_database,node_service_bindings toneMint
class node_conversation_service,node_chat_controller,node_chat_agent,node_task_notifications,node_telegram toneRose
```

## Components

### Client Interfaces

- [REST API](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Http/Controllers/Api): `app/Http/Controllers/Api`
- [MCP Server Tools](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Mcp/Tools): `app/Mcp/Tools`
- [MCP Server](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Mcp/Servers/HospitableServer.php): `app/Mcp/Servers/HospitableServer.php`

### Domain Services

- [Project Service](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Projects/Services): `app/Domain/Projects/Services`
- [Task Service](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Tasks/Services): `app/Domain/Tasks/Services`
- [Financial Services](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/Financials/Services): `app/Domain/Financials/Services`
- [Report Service](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Reports/Services/ReportService.php): `app/Domain/Reports/Services/ReportService.php`
- [User Service](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Users/Services/UserService.php): `app/Domain/Users/Services/UserService.php`
- [Creation Ideas](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Domain/CreationIdeas/Services): `app/Domain/CreationIdeas/Services`
- [Aggregated Reports](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Reports/Services/ReportService.php): `app/Domain/Reports/Services/ReportService.php`

### Persistence

- [Eloquent Repositories](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Infrastructure/Persistence/Eloquent): `app/Infrastructure/Persistence/Eloquent`
- [Domain Models](https://github.com/wolneydev/northloom-laravel/tree/prod/app/Models): `app/Models`
- **Database**
- [Service Bindings](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Providers/AppServiceProvider.php): `app/Providers/AppServiceProvider.php`

### Chat and Notifications

- [Conversation Service](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Conversations/Services/ConversationService.php): `app/Domain/Conversations/Services/ConversationService.php`
- [Chat Controller](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Http/Controllers/Api/ChatController.php): `app/Http/Controllers/Api/ChatController.php`
- [Chat Agent](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Ai/Agents/HospitableChatAgent.php): `app/Ai/Agents/HospitableChatAgent.php`
- [Task Notifications](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Domain/Tasks/Services/TaskNotificationService.php): `app/Domain/Tasks/Services/TaskNotificationService.php`
- [Telegram Delivery](https://github.com/wolneydev/northloom-laravel/blob/prod/app/Infrastructure/Telegram/TelegramNotificationService.php): `app/Infrastructure/Telegram/TelegramNotificationService.php`

### Other components

- **HTTP Client**
- **MCP Client**
- **Chat User**

## Connections

- HTTP Client → REST API: calls
- REST API → Project Service: delegates to (evidence: `app/Http/Controllers/Api/ProjectController.php`)
- REST API → Task Service: delegates to (evidence: `app/Http/Controllers/Api/TaskController.php`)
- REST API → Financial Services: delegates to
- REST API → Report Service: requests reports
- REST API → User Service: manages users
- REST API → Creation Ideas: requests ideas
- MCP Client → MCP Server: connects via stdio
- MCP Server → MCP Server Tools: exposes tools
- MCP Server Tools → Project Service: delegates to
- MCP Server Tools → Task Service: delegates to
- MCP Server Tools → Financial Services: delegates to
- MCP Server Tools → Report Service: requests reports
- MCP Server Tools → Creation Ideas: suggests ideas
- Chat User → Chat Controller: sends message
- Chat Controller → Chat Agent: invokes agent (evidence: `app/Http/Controllers/Api/ChatController.php`)
- Chat Agent → MCP Server: uses local MCP
- REST API → Chat Controller: serves chat API
- Task Service → Task Notifications: schedules reminders
- Task Notifications → Telegram Delivery: delivers via (evidence: `app/Infrastructure/Telegram/TelegramNotificationService.php`)
- Project Service → Eloquent Repositories: persists through
- Task Service → Eloquent Repositories: persists through
- Financial Services → Eloquent Repositories: persists through
- Eloquent Repositories → Domain Models: queries and updates (evidence: `app/Infrastructure/Persistence/Eloquent/EloquentTaskRepository.php`)
- Domain Models → Database: stores records
- Service Bindings → Eloquent Repositories: binds implementations (evidence: `app/Providers/AppServiceProvider.php`)
- Service Bindings → Telegram Delivery: binds delivery (evidence: `app/Providers/AppServiceProvider.php`)
- Report Service → Aggregated Reports: produces
