# Getting Started With Iwf

Iwf is a full-stack Idris web framework. One Idris codebase owns routes,
controllers, HTML, forms, JSON APIs, SQL, tests, and development tooling.

Iwf is inspired by the productive shape of IHP, but it is not an IHP
compatibility layer. The guide below focuses on the code you write in an Iwf
app first. Internals and roadmap details are linked later.

## Learning Path

If you are new to Iwf, follow these pages in order. Each page builds on the
previous one.

### 1. Getting Started

- [Installation](installation.md): enter the development shell, build the
  framework, run the canonical app, and run the main checks.
- [Your First Project](your-first-project.md): generate a small app, change the
  first page, add a route, add a schema table, and see where generated code
  lives.
- [First CRUD Feature](first-crud-feature.md): build one article feature with a
  path route, form, table, TypedSQL query, validation, auth, live fragment, and
  `iwf check`.
- [Architecture](architecture.md): understand the normal `Application/`,
  `Config/`, and `Web/` layout.
- [Config and Server](config-and-server.md): configure ports, sessions,
  database access, logging, request limits, and server startup.

### 2. Core Concepts

- [Routing](routing.md): map URLs to Idris handlers and generate links from the
  same route values.
- [Controllers](controllers.md): handle requests, render pages and fragments,
  redirect users, and protect routes.
- [Views and IDRX](views-and-idrx.md): write HTML-like `.idrx` files that
  compile into checked Idris.
- [Forms and Validation](forms-and-validation.md): build route-backed forms,
  preserve submitted values, and show field errors.
- [Database and Migrations](database-and-migrations.md): define the schema in
  PostgreSQL SQL, generate Idris row types, run migrations, and use the runtime
  database pool.
- [TypedSQL](typed-sql.md): write raw SQL that PostgreSQL describes before the
  Idris module compiles.

### 3. Common App Features

- [JSON API and OpenAPI](json-api-and-openapi.md): reuse route metadata for JSON
  endpoints and Swagger/OpenAPI docs.
- [Sessions, Cookies, Flash, and CSRF](sessions-cookies-flash-csrf.md): use
  signed sessions, flash messages, raw cookies, and CSRF protection.
- [Authentication and Authorization](authentication-and-authorization.md): add
  login, current-user lookup, route guards, Basic Auth, OAuth/passkey adapter
  boundaries, and account safety helpers.
- [Jobs, Scripts, and Mail](jobs-scripts-and-mail.md): run background jobs,
  app-context scripts, typed mail, and development mail previews.
- [File Uploads and Storage](file-uploads-and-storage.md): decode multipart
  uploads and store files locally or through S3-compatible storage.
- [Integrations, I18n, and Payments](integrations-i18n-and-payments.md): add
  translations, locale selection, Stripe Checkout, webhooks, OAuth, and passkey
  integration boundaries.

### 4. Frontend

- [HTMX, Auto Refresh, and Modals](htmx-auto-refresh-and-modals.md): use the
  default boosted shell, modal host, fragment rendering, and scoped live refresh.
- [Assets and Styling](assets-and-styling.md): serve framework assets, app
  assets, fingerprinted files, Basecoat defaults, and development reload
  helpers.
- [Navigation, Pagination, and SEO](navigation-pagination-and-seo.md): render
  navigation, breadcrumbs, pagination, page head metadata, OpenGraph tags, and
  sitemaps.

### 5. Going Further

- [Dependent Routes and Forms](dependent-routes-and-forms.md): learn how the
  dependent types connect `pathTo`, request decoding, and IDRX form checks.
- [PostgreSQL Runtime Architecture](postgresql-runtime-architecture.md): read
  the database adapter contract and current helper implementation.
- [Internal Technical Architecture](../technical-architecture.md): read the
  maintainer-level architecture, code organization, subsystem boundaries, and
  known shortcomings.
- [IHP Migration Notes](../ihp-migration.md): compare Iwf's public surface with
  IHP and see which IHP features are intentionally out of scope.

### 6. Production and Maintenance

- [Security and Deployment](security-and-deployment.md): validate production
  config, install security headers, use RLS request context, and follow the
  deployment checklist.
- [Testing and Debugging](testing-and-debugging.md): run framework tests,
  acceptance harnesses, route tests, diagnostics, and browser request debugging.
- [Troubleshooting](troubleshooting.md): fix common setup, build, browser,
  Auto Refresh, TypedSQL, asset, and OpenAPI problems.

## What Iwf Gives You

- Typed routes with typed path, query, JSON body, form body, and multipart body
  decoding.
- `pathTo` and redirect helpers that reuse the same route values used by
  dispatch.
- Direct `.idrx` HTML that turns into checked Idris source.
- A default htmx/morphdom/Basecoat shell with stable main content, flash, modal,
  and Auto Refresh hosts.
- HTML pages, HTMX fragments, JSON endpoints, and OpenAPI docs from route
  metadata.
- PostgreSQL schema typegen, migrations, fixtures, generated model records,
  TypedSQL, and pool-backed runtime execution.
- Auth, signed cookie sessions, CSRF, flash, authorization helpers, jobs, mail,
  uploads, Stripe helpers, i18n, SEO, pagination, navigation, and test helpers.
- `iwf check` for the canonical repository and app verification path.

## What Iwf Does Not Try To Be

Iwf intentionally does not provide an IHP compatibility layer, query-builder DSL,
model-backed forms, generated relationship helpers, validation metadata on
generated database rows, IHP DataSync, public typed WebSocket routing,
server-side components, a first-class NPM/Yarn workflow, a browser IDE, or
compatibility shims for renamed APIs.

## Next

Start with [Installation](installation.md).