RFC: Inital structure / design

[ritch]

/to @raymondfeng @bajtos @seanbrookes
/cc @altsang

Looking for feedback on the list below. A code review would not be helpful at this point as things are going to change drastically.

Need Feedback on the Following:

• high level design
• file structure
• build approach
• loopback.Remote usage

TBD Still In Progress

• Angular Controller Implementation
• Views
• HTML / CSS

[raymondfeng]

From the structure perspective, I prefer to see some isolations at directory level instead of file level. For example,

/server
  /views
/client
  /controllers
/common (or shared)

Did you look at https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub?

[ritch]

Directory level organization seems to be the winner so far.

We can't really call it "client" though. You might have 10 clients and just one of them is angular app.

[bajtos]

Static middleware must be always the last request handling middleware, registered just before loopback.urlNotFound and loopback.errorHandler. Otherwise every HTTP request hits the disk to check if there is a file matching the requested URL.

[bajtos]

I agree with @raymondfeng, moving server-specific files and angular-client-specific files to isolated directories would help.

We can't really call it "client" though. You might have 10 clients and just one of them is angular app.

What other html5-based clients do you expect? If there is only one html5 client and the other clients are native apps, then perhaps "client" subdirectory of the http/web server app is not that confusing.

We can use a different name by combining one of "web", "browser", "angular", "html5" with "app" or "client". E.g. html5app.

---

I would like to structure the files as functional/logical blocks, e.g. all files for the "User" model should be close together, as opposed to spreading the files across common/client/server directories.

models/
  user.js
  user.server.js
  user.client.js
  test/
    user.test.js

server/
  app.server.js
  test/
    app.server.test.js

html5app/
  controllers/
  css/
  templates/
  app.html5.js
  test/
    app.html5.test.js

common/
  utils.js
  test/
    utils.test.js

test.e2e/
  # end-to-end tests

[bajtos]

The configuration of loopback.Remote connector must be kept outside of app.browser.js as it will differ between environments (dev, staging, production). Can the server app inject the config when serving the SPA bundle? That way it's possible to deploy the same set of source files to different environments, without having to re-build app.browser.js at deploy time.

[ritch]

I like @bajtos proposed structure.

@seanbrookes @raymondfeng thoughts?

[ritch]

@bajtos some comments inline:

models/
  user.js
  user.server.js
  user.client.js
  test/
    user.test.js // would this include browser and server tests?

server/
  app.server.js
  test/
    app.server.test.js

html5app/
  controllers/
  css/
  templates/ // in this app we use some server side ejs templates and some client templates - should we have two directories to show this separation? should you be able to share templates?

  app.html5.js
  test/
    app.html5.test.js

common/
  utils.js // is this for code that can be used anywhere?
  test/
    utils.test.js

test.e2e/
  # end-to-end tests

I guess my issue with the strict separation is that ideally you just write JavaScript against an interface. You shouldn't have to write "browser js" and "server js" at the app level. Maybe in plugins / modules you should do this...? Just thinking out loud really.

On the other hand, the strict separation is very clear and easy to understand / reason with.

[bajtos]

@ritch

models/test/user.test.js // would this include browser and server tests?

I suppose you can have three sets of tests:

• pure unit-tests using code from user.js that should be run in all environments
• integration tests for the server (user.server.test.js) that test user.js and user.server.js
• integration tests for the browser that test user.js and user.client.js

If your model is "pure" and does not use anything client or server specific, then pure unit-tests are probably sufficient and you can run them in both environments.

I find it difficult to think through all details in advance, we will get the best feedback when we write the first model.

---

html5app/templates/
// in this app we use some server side ejs templates and some client templates
// should we have two directories to show this separation? 
// should you be able to share templates?

I was thinking about an encapsulated client app (a single-page app) that interacts with the server exclusively via the REST API. Something similar to what Trello is doing (link).

In which case there are no shared templates.

What would you like to share?

---

common/utils.js // is this for code that can be used anywhere?

Yes, this should be pure JS code that can be used in all environments. The idea is building on top of Raymond's proposal. I am sure it can be improved a lot.

Maybe instead of common directory, there should be a generic concept of components/plugins, each component living in a subdirectory and containing shared/client/server source. Or maybe there should be nothing else except models, server and html5app. We have to find out :)

[bajtos]

Ad 2b3b144 - bower_components should be IMO git-ignored in the same way as node_modules.

[bajtos]

The new structure looks great 👏

[bajtos]

Here are the steps needed to keep bower dependencies outside of git:

1. Create bower.json file (example: looopback-angular/bower.json)
2. Add pre-test or post-install script running "bower install" (example: loobpack-angular/package.json)

[bajtos]

@ritch could you please merge the first version without replication? That way I can start my work on extracting LoopBack - AngularJS integration into a standalone module that can be refactored into SDK later.