JCC Express

Getting Started

Directory structure

JCC Express MVC projects follow a Laravel-style layout: application code under app/, HTTP entry through bootstrap/ and server.ts, routes in route/, database artifacts in database/, front-end assets in resources/, and the framework core in jcc-express-mvc/ (or equivalent when the package is installed from npm).

Exact folders can vary slightly if you trimmed a starter template, but the paths below match a full reference application.

Top level

text
project-root/
├── app/                 # Your application code
├── bootstrap/           # App bootstrap (creates the Application instance)
├── database/            # Migrations and seeders
├── final-documentation/ # Curated framework documentation (canonical doc set)
├── jcc-express-mvc/     # Framework package (often vendored in the repo)
├── public/              # Static files served to the browser
├── resources/           # Views, JS/CSS sources (Vite)
├── route/               # Route definitions (web, api, etc.)
├── storage/             # Writable storage (sessions, uploads, logs, queue file)
├── tests/               # Automated tests (Feature / Unit)
├── server.ts            # Process entry: imports bootstrap and runs the app
├── package.json
├── tsconfig.json
├── vite.config.ts     # Vite (when using Inertia / SPA tooling; .ts also common)
└── .env                 # Local configuration (not committed)

Other roots you may see in a mature repo include design/ (schemas, design notes), Testing/ (framework-style test helpers), Interface/, or Models/—treat those as project-specific unless your starter created them.

app/ — application code

  • Config/ — Typed config modules merged in app/Config/index.ts (see Configuration).
  • Http/ — kernel.ts, Controllers/, ApiControllers/, Middlewares/, Requests/, Resources/.
  • Models/ — Eloquent, Sequelize, and Mongoose models (@/Models/* path alias).
  • Entities/ — TypeORM entity classes (when DB_ORM=typeorm).
  • Providers/ — Service providers (AppServiceProvider, queues, sockets, etc.).
  • Console/Command/ — Custom artisanNode commands.
  • Jobs/ — Queue job classes.
  • Events/, Listener/ — Event and listener classes.
  • Mail/ — Mailables and mail-related code.
  • Policies/ — Authorization policies.
  • Observer/ — Model observers.
  • Services/, Repository/ — Domain and data-access layers (common convention).
  • Commands/ — Extra console or app commands (if present).
  • Examples/ — Sample or demo code (optional).
  • Scope/ — Query scopes (optional).

bootstrap/

  • app.ts — Builds the Application with .withRouting(), .withConfig(), .withProviders(), .withKernel(), .withMiddleware(), then .create().
  • providers.ts — Array of service provider classes actually registered at runtime.
  • ssr/ — Inertia SSR build output / server bits when SSR is enabled.

route/

Route modules loaded by name from bootstrap/app.ts (for example route/web, route/api with optional URL prefixes).

Typical files:

  • web.ts — Browser routes (Inertia, sessions, CSRF).
  • api.ts — JSON / token-style API routes.
  • admin.ts or others — Optional route groups.

database/

  • migrations/ — Timestamped migration files (bun artisanNode migrate).
  • seeders/ — DatabaseSeeder and focused seeders (bun artisanNode db:seed).

resources/

  • views/ — Blade (or other) templates, often under resources/views. Layouts and partials live here.
  • js/ — Inertia/React/Vue entry points and pages.
  • css/ — Stylesheets processed by Vite.

See Frontend for how main.jsx, Pages/, Vite, and @inertia fit together.

public/

Static assets and the Vite build output (for example public/build). Put favicons, images, and robots.txt here. The HTTP server exposes this tree as the web root where configured.

storage/

Runtime-writable data:

  • sessions/ — File session driver (see app/Config/session.ts).
  • app/ — Uploads, generated files, private cache (convention).

Do not commit sensitive storage/ contents; .gitignore usually excludes most of it.

jcc-express-mvc/

The jcc-express-mvc npm package provides routing, the service container, Eloquent integration, artisanNode, queues, Inertia helpers, Socialite, mail, validation, and more. Import the main API from jcc-express-mvc and jcc-express-mvc/Core.

When you depend on the framework from npm, the same concepts apply—the package lives in node_modules/jcc-express-mvc/.

tests/

  • Feature/ — HTTP and integration tests.
  • Unit/ — Isolated unit tests.

The framework ships a TestCase base class you extend in tests/TestCase.ts — it boots the app and exposes HTTP and database helpers.