Architecture: Best Practices and Architecture about software-engineering-daily-api

[joshmorel]

Yes I think an example would help a lot with getting on the same page. 🙂 I'll apply it to a small feature with documentation and we can discuss around a PR.

[TheHollidayInn]

Yep! You are in the right path. I mentioned both of those architectures above. But you do grow into them for small projects. The main guides are keeping the SOLID patterns, removing code smells and keeping business logic out of MVC. They both have books on the subjects

[joshmorel]

Cool I'll do some more research but leave this on the back-burner/low-priority for now.

[edgar971]

I think that's a good idea.

[edgar971]

Perhaps we should consider Git Flow as the workflow for Git and branching. It's recommended for open source projects to keep high quality and fewer bugs.

In the Git flow development model, you have one main development branch with strict access to it. It’s often called the develop branch.

Developers create feature branches from this main branch and work on them. Once they are done, they create pull requests. In pull requests, other developers comment on changes and may have discussions, often quite lengthy ones.

[TheHollidayInn]

Ah yea! We should. I use that at work now, and it is great.

[joshmorel]

From looking through everything I have a few comments about structuring of the api code with regards to controllers, routes and models.

• It seems like there is repetition across the model and controller methods as well as inconsitency in terms of usage. For example vote.controller.list uses vote.model.list but vote.controller.upvote uses just mongoose methods. It would be helpful for contributors (and maintenance) if we had a defined best practice for what code goes where. Perhaps, IMHO, the model could include only methods for revealing specific instances as JSON (toJSON, toJSONFor(post/user/etc)) with everything else (get, query, etc) in the controllers? I can provide an example through a PR but am very open for other ideas.
• For simplicity of organization, would it make sense to co-locate controllers and routes?

[TheHollidayInn]

Yea, I agree for the most part. We will want to expand to one of the better clean/hex patterns.

The controllers are separated from the routes, which was the main point, but have the repetition on the model doesn't make much sense as the controller is kind of like a repository. It does keep express separated from mongoose though, which is good.

By co locate, do you mean organize by entity? As in have a folder for post, favorites, etc? I think that is something we can go ahead with.

[joshmorel]

It might help to define the responsibilities of each component. From my understanding:

• controllers: provide logic for responding to requests to each route (or more, basically, the route callback function)
• models: provide relationship between app and database with data access methods
• routes: the actual http routes

I'm fine with the route/controller separation because it's consistent, although I do struggle with it a bit because of the one-to-one mapping between routes and controllers (should they not be combined?). More importantly would be to consistently separate the models and controllers. You could define a lot of the logic in mongoose methods but if it's better for scalability/maintenance to make the mongoose implementations indepedent of the controller logic we should do that and consistently (with exceptions allowed where it makes sense).

I'd be willing to provide a stab at doing so, either with a new request (user profile? - an open issue) or with existing code. Let me know your thoughts and I'll go ahead.

Also, what's the status on implementing flow type checking? Is it stalled?

[TheHollidayInn]

I'm not really following what improvements you are wanting to make. Are you just saying there is too much connection between one to one methods? As in, route list -> list method on controller -> list method on the model.

Currently things are in a standard MVC/Express flow. Your responsibilities are pretty much correct, but as we expand, we introduce layers in between controllers and models (Domain Layer, Interactors, Entities, Repositories)

• If you want to reorganize the folders, that is fine.
• If you want to provide an example of your suggested flow, feel free to make a PR on an existing feature. Just make sure it is small in scope and has a reference to a proven architecture pattern/code refactor

Type checking has a PR open and a contributor working. It isn't a high priority, and they have requested time.

[joshmorel]

I don't have anything yet to share unfortunately... I've been doing a bit of research while trying out different things and this seems like the most appealing option, applying Uncle Bob's clean architecture with similarities also to Alistair Cockburn's hex architecture.

Basically the idea is that you put the core of the app and business logic in something called a "user-case interactor". This then has interfaces or ports to the implementation stuff - so the ORM/ODM, the REST framework, etc.

So assuming we keep everything else the same, you'd basically have the following sections:

• app: the core logic (user-case interactors)
• controller: the delivery mechanism or REST API (Express) stuff
• route: the exposed end-point of the controller (keeping it separate from controller seems like it could still be helpful for versioning etc)
• model: the database (Mongoose) stuff

However at this stage in the app, the added layer is probably more effort than value given the early stage and smaller team. Perhaps something to keep in mind in the future as the complexity grows?

In the interim... some improvements to separation could be made by keeping all the mongoose stuff in the model (a decent chunk is in the controllers). But just refactoring would be low value at this point - maybe addressing this while fixing a small issue or implementing something new might provide the most value? Let me know if there's low hanging fruit you'd want work on and I can take a stab.