Request for Guidance: Application Structure & Best Practices for Enterprise Applications

[koufopoulosf]

What is the feature you are proposing?

Overview

As a developer building enterprise applications with Hono.js, I've had to make many architectural decisions to maintain separation of concerns, dependency injection, validation, and documentation. While Hono's unopinionated nature is valuable, some guidance on recommended patterns would be extremely helpful to reduce cognitive overhead and establish conventions.

Current Structure

I've implemented the following structure for a medium-to-large application using Hono:

/src
├── core/                      # Core application components
│   ├── db/                    # Database schema and migrations
│   ├── errors/                # Error handling system
│   ├── factories/             # Creation factories
│   ├── logging/               # Logging utilities
│   └── monitoring/            # Monitoring and observability
│
├── features/                  # Feature modules
│   ├── auth/                  # Authentication feature
│   ...
│   └── users/                 # User management
│       ├── me/                # User profile management
│       ├── media/             # Media handling
│       └── notifications/     # User notifications
│
├── integrations/              # Third-party service integrations
│   ├── assets/                # Asset management
│   ├── cache/                 # Caching system
│   ├── database/              # Database connection
│   ├── email/                 # Email services
│   ├── firebase/              # Firebase integration
│   └── phone-verification/    # Phone verification services
│
├── shared/                    # Shared utilities and components
│   ├── middlewares/           # Application middlewares
│   ├── services/              # Shared services
│   └── utils/                 # Utility functions
│
├── app.ts                     # Main application setup
├── container.ts               # DI container setup
├── index.ts                   # Application entry point
└── openapi.ts                 # OpenAPI integration

Each feature module follows this pattern:

/feature
├── api/                 # HTTP endpoints
├── di.ts                # Dependency injection registration
├── docs/                # Documentation
│   ├── diagrams/        # Flow diagrams
│   ├── notes/           # Implementation notes
│   └── openapi/         # OpenAPI specification
├── index.ts             # Feature exports
├── repositories/        # Data access
├── services/            # Business logic
│   ├── domain/          # Core business logic
│   └── infrastructure/  # Technical services
├── types/               # Type definitions
├── use-cases/           # Application use cases
└── validation/          # Input validation

Pain Points

1. Dependency Injection: Since Hono doesn't have built-in DI, I'm using Awilix, which creates additional boilerplate code in each feature module.

2. Validation/DTOs: There's no standardized approach for input validation, resulting in custom solutions and additional cognitive overhead.

3. API Documentation: Creating and maintaining OpenAPI docs manually is time-consuming.

4. Code Organization: The current structure follows a clean architecture approach but results in many files and directories, creating a high cognitive load when working with the codebase.

5. Use-Case Pattern: I've implemented a use-case pattern to coordinate services and prevent circular dependencies (1 API <> 1 USE CASE <> N SERVICES <> N REPOSITORIES), but I'm unsure if this is the right approach.

Questions

1. Is there a recommended application structure for larger Hono.js applications that balances separation of concerns with developer experience?

2. What are the best practices for organizing code in a Hono.js application to avoid the "boilerplate trap"?

3. Are there any recommended libraries or patterns for handling common concerns like validation, DI, and API documentation that work well with Hono?

4. Would a more file-based routing approach (like Next.js) with colocation of logic be more appropriate for Hono applications?

5. Could the Hono documentation include examples of different application structures based on application size and complexity?

Community Feedback

Several developers have expressed similar concerns on various platforms. The consensus seems to be that while Hono's unopinionated nature is valuable, some guidance on recommended patterns would help developers make better architectural decisions and avoid reinventing the wheel.

Potential Solutions

1. Official Structure Templates: Provide example structures for different sizes of applications (small, medium, large).

2. Best Practices Guide: Document recommended approaches for common concerns like validation, DI, and API documentation.

3. Starter Kits: Create official starter kits or templates that implement proven patterns.

4. Community Showcase: Feature community projects that demonstrate effective structures for various use cases.

Thank you for considering this request. Hono is a fantastic framework, and some guidance on these points would make it even more accessible for complex applications.

[EdamAme-x]

This is something I often see people mention about Hono. It’s kind of a docs issue, but I think it’s fine to talk about it here.

Examples
https://zenn.dev/link/comments/83086adda0cd17
https://x.com/ikkitang/status/1863481838381203701
https://x.com/charlie_rebirth/status/1915720393454752158

[yusukebe]

I know that the challenging aspect is designing the structure with an un-opinionated framework, such as Hono, to build large applications (I faced this when using Golang).

I think our official docs don't have to show the details of the application structure since the official docs should be minimal, but we can link to them:

• "XXX stack," which utilizes Hono and other components with an opinionated design.
• Meta frameworks like HonoX, which enable the user to follow one of the best practices.
• Application Structure and Best Practices Guide.