README.markdown

Shogun

Shogun is a light weight, and yet powerful, Ruby web application framework. It's robust design allows for distributed web applications that span multiple servers, databases, and APIs. What does that mean, though?

• Shogun is a PAC architecture, the only one, and the unique architecture allows it to stay up even under the harshest conditions
• Shogun as a framework is database, template, style, script, testing library, and even language agnostic (to a degree)
• Shogun uses Zed Shaw's famous (and reliable) web server named Mongrel 2

Installing

To start with Shogun, all you need to do is have Ruby 1.9, a database (try MongoDB or Riak), and Mongrel 2:

$ brew install mongrel2
$ rvm install 1.9.3 && rvm --create @shogun.app
$ gem install shogun

Now you've got a stable install of shogun in your gems.

From here you can start to create your application using the special shogun create command that comes with Shogun. Except for the initial create command all of Shogun's tools and tasks use the thor gem. Shogun strives to design by the principle of least surprise. The flags in [] are optional, and the values given are the default.

$ shogun create appname [--abstractor ripple]  [--presenter dapperdan]  [--style sassy] [--script coffeescript] [--test rspec] [--extra spork, vcr, capybara, heroku]

$ thor serve [--port 3000] [--environment development] [--agent all]

$ thor build daimyo [--scaffold] [--no-presenter][--no-abstractor] [--no-control]
$ thor build domain Accounts [--abstraction email:string, password:encrypted, age:number] [--controller index show new create edit update] [--presenter index show new edit]

Structure

An example twitter application:

twitter/
  - daimyo/
    - "See: The Daimyo"
  - domains/
    - "See: Your Domains"
  - database/
    - "See: Databases"
  - lib/
    - environments/
      - "See: Environments"
    - application.rb
  - tests/
  - vendor/
  - logs/
  - tmp/
  - Gemfile
  - Gemfile.lock
  - Guardfile
  - Thorfile

The Daimyo

daimyo/
  - presentation.rb
  - presentations/
    - pages/
      - splash.html.erb
      - beta.html.erb
      - jobs.html.erb
      - policy.html.erb
      - terms.html.erb
  - abstraction.rb
  - control.rb

The daimyo directory is where all of the top level application logic is stored. This is very similar to the app directory of a rails application. Notice, in this example, two things:

• Shogun's Presentation, Abstraction, and Control concepts are contained in three ruby files.
• There's another folder, which contains a generic Presentation (pages/).

As the pages/ category is generic enough, they're allowed to exist in the daimyo directory. If you were to compare this to a rails application, the controls.rb file would also contain the routes.rb logic.

# Shogun.root/daimyo/controls.rb

Shogun::Control.routes do
  push :account, to: AccountRoku
  push :stream, to: StreamRoku

  push get: "login", to: AccountRoku.route :session, :new
  push get: "signup", to: AccountRoku.route :authentication, :new
  push get: "signout", to: AccountRoku.route :session, :destroy
end

Domains

    - accounts_roju/
      - presentations/
      - abstractions/
      - controls/
      - authentication_clan/
        - presenters/
        - abstractions/
        - controls/
      - authorization_clan/
        - presenters/
        - abstractions/
        - controls/
      - session_clan/
        - presenters/
        - abstractions/
        - controls/
      - profile_clan/
        - presenters/
        - abstractions/
        - controls/
    - streams_roju/
      - presentations/
      - abstractions/
      - controllers/
      - list_clan/
        - presentations/
        - abstractions/
        - controls/
      - feed_clan/
        - presentations/
        - abstractions/
        - controls/