---
title: Project Structure
description: Each file in an Elevasis SDK project and its purpose in the development workflow
loadWhen: "Understanding scaffolded files or project layout"
---

Your Elevasis SDK project includes a complete workspace structure. This page explains what each file does and when you will interact with it.

The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `core/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `core/` package for cross-runtime types, schemas, and organization-model configuration.

---

## Source Files

### `operations/src/index.ts`

The registry entry point for your workspace. This file imports OM resource governance from `core/config/organization-model.ts`, aggregates executable resources from domain barrel files, and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is assembly:

```ts
import type { DeploymentSpec } from '@elevasis/sdk'
import { organizationModel } from '@core/config/organization-model'
import * as example from './example/index.js'
import * as emailNotification from './email-notification/exports.js'

const org: DeploymentSpec = {
  version: '0.1.0',
  organizationModel,
  workflows: [...example.workflows, ...emailNotification.workflows],
  agents: [...example.agents, ...emailNotification.agents]
}
export default org
```

Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays.

### `operations/src/email-notification/index.ts`

A multi-step workflow demonstrating real platform API usage. Sends an email notification using the `notifications` adapter and chains steps with `StepType.LINEAR`. Shows the pattern for workflows that use platform tool adapters and pass data between steps.

### `operations/src/example/echo.ts`

The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. Replace this domain with your own when you're ready.

### `core/`

Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code. Resource descriptors live in `core/config/organization-model.ts`.

### `operations/elevasis.config.ts`

Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`):

```ts
import type { ElevasConfig } from '@elevasis/sdk'

export default {
  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
  // dev: { port: 5170 },      // Local API port (internal development only)
} satisfies ElevasConfig
```

---

## Documentation

### `docs/index.md`

The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis-sdk deploy` and rendered in the Elevasis platform UI.

Use MDX frontmatter to set page metadata:

```yaml
---
title: Overview
description: Documentation for this project
order: 0
---
```

Add more pages by creating additional `.mdx` files in `docs/`. Nested directories create sections: `docs/guides/setup.mdx` becomes a `guides/setup` page under your deployment's documentation.

### `docs/project-map.mdx`

Auto-generated by `elevasis-sdk deploy` on every deploy and by `/meta fix` step 8. Contains a full project snapshot: organization, SDK version, template version, last deploy date, source domains, resource tables (workflows and agents), documentation index, SDK reference summary, commands/rules/skills, memory system listing, and configuration state. The agent reads this file at session start for project orientation.

This file is fully auto-generated -- do not edit manually. Changes are overwritten on the next deploy.

### `docs/priorities.mdx`

Created by the agent during your first goal discussion. Records current goals, priorities, and next steps for the workspace. Updated as goals change across sessions.

This file is NOT scaffolded by default. The agent creates it the first time you discuss project goals or priorities in a session.

### `docs/in-progress/`

Work-in-progress task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. This is separate from the Projects data model exposed through `elevasis-sdk project:*`. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.

This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis-sdk deploy`.

---

## Progressive Disclosure Directories

The following directories are included in the scaffold:

| Directory                            | Created by      | When                                                               |
| ------------------------------------ | --------------- | ------------------------------------------------------------------ |
| `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
| `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
| `core/`                              | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
| `ui/`                                | Scaffold        | Always -- React frontend application                               |
| `docs/`                              | Scaffold        | Always                                                             |
| `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
| `docs/resources.md`                  | `/deploy` skill | Auto-generated on every deploy                                     |
| `data/`                              | Agent           | When you connect a database                                        |
| `scripts/`                           | Agent           | When you need local scripts not deployed to the platform           |
| `operations/src/lib/`                | Agent           | When shared code exists between two or more workflows              |

This structure keeps the initial workspace minimal and adds directories only when they earn their place.

### `operations/src/lib/`

Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `core/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.

### `data/`

Created by the agent when you connect a database. Contains `schema.ts` which documents your database schema as TypeScript types. The agent reads this file to understand your data model when writing workflow steps that call the Supabase tool. Not deployed -- it is local documentation for the agent.

### `scripts/`

Local utility scripts for tasks that do not run on the platform: database seeds, data migrations, one-off transformations, local testing helpers. Created on demand when you need a local script. Not deployed, not bundled.

---

## `elevasis-sdk deploy` Scope

`elevasis-sdk deploy` touches only two directories:

| Directory           | Action                                                                               | Deployed? |
| ------------------- | ------------------------------------------------------------------------------------ | --------- |
| `operations/src/`   | Bundle into `dist/bundle.js` via esbuild (includes `operations/src/lib/` if present) | Yes       |
| `docs/`             | Scan `.md` and `.mdx` files, upload as documentation                                 | Yes       |
| `docs/in-progress/` | Ignored -- work-in-progress, not deployed                                            | No        |
| `data/`             | Ignored -- local documentation for the agent                                         | No        |
| `scripts/`          | Ignored -- local scripts, not deployed                                               | No        |
| `.claude/`          | Ignored -- local development only                                                    | No        |
| `ui/`               | Ignored -- frontend application, deployed separately                                 | No        |

---

## Configuration Files

### `.env`

Contains your `ELEVASIS_PLATFORM_KEY`. This file is gitignored. Never commit it.

### `.npmrc`

Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.

### `tsconfig.json`

App-focused TypeScript configuration. It does not include `declaration` or `declarationMap` settings because your project is a deployable application, not a library.

### `.gitignore`

Pre-configured to exclude:

- `node_modules/` -- installed packages
- `.env` -- API key
- `dist/` -- generated by deploy, never commit
- `__elevasis_worker.ts` -- temporary file generated during deployment
- `.claude/settings.local.json` -- local Claude Code overrides
- `.claude/memory/` -- your personal cross-session project memory (profile, errors, decisions)

---

## Claude Code Integration

The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and your project structure from the first session.

### `CLAUDE.md`

The most important file for AI-assisted development. It provides Claude Code with:

- **Project orientation** -- what an Elevasis SDK project is and how it works
- **Project structure** -- which files contain resources, documentation, and configuration
- **SDK patterns** -- working code examples for descriptor-backed resource definitions, Zod schemas, and the `DeploymentSpec` export
- **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
- **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)

Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that makes the slash commands work well.

### `.claude/settings.json`

Configures Claude Code for the workspace: registers a PostToolUse formatting/type-check hook (runs after Write, Edit, and MultiEdit) and a PostToolUseFailure error recovery hook (runs after Bash failures).

### `.claude/memory/`

Created when you run `/meta init` in Claude Code. The agent asks six onboarding questions about your organization, project goals, integrations, and experience level. Answers are stored here as markdown files and used to personalize subsequent sessions.

```
.claude/memory/
├── index.md                    # Root index linking all memory topics
├── profile/                    # Developer profile (created by /meta init)
│   ├── index.md
│   ├── identity.md             # Organization, goals, integrations
│   ├── skills.md               # Skill dimensions and Growth Log
│   └── preferences.md          # Verbosity and guidance style
├── deployment-state.md         # Latest deployment outcomes
├── decisions.md                # Architecture decisions recorded over time
└── errors/                     # Error patterns and resolutions
```

This directory is gitignored -- it is personal to you and not shared with collaborators. All cross-session knowledge (profile, errors, deployment state, decisions) lives here as plain markdown.

---

## Slash Commands

The `.claude/skills/` directory contains skills covering the core development loop:

- **`/setup`** -- First-time project setup: placeholder replacement, deps, verification
- **`/deploy`** -- Full deploy pipeline: test, build, commit, push
- **`/elevasis`** -- SDK operations: check, deploy, exec
- **`/work`** -- Task tracking across sessions: auto-detects intent (create, save, resume); suggests complete
- **`/status`** -- Quick project health check
- **`/save`** -- Auto-manage docs from conversation context
- **`/explore`** -- Codebase exploration anchored to docs
- **`/continue`** -- Resume in-progress work from docs
- **`/project`** -- Routes project management to the canonical `elevasis-sdk project:*` commands
- **`/dsp`** -- Parallel agent dispatch for implementation tasks
- **`/sync`** -- Pull latest, wipe caches, fresh reinstall

Boundary summary:

- `/project` updates shared project records
- `/work` manages docs-backed work tracking
- `/adev` handles implementation and execution work

For detailed command documentation, see [Agent System](agent).

---

## File Classification

Not all scaffolded files participate in template updates. Files fall into two categories:

**SCAFFOLD_FILES total: 32**

**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:

- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
- `.env`, `.npmrc`
- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `core/`
- `docs/index.md`, `docs/in-progress/.gitkeep`

**MANAGED** -- Written during initial scaffold and updated when the template evolves:

- `operations/elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
- Two hooks: `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
- Skills: `.claude/skills/work/SKILL.md`, `.claude/skills/elevasis/SKILL.md`, `.claude/skills/deploy/skill.md`, `.claude/skills/setup/SKILL.md`
- Rule files: `.claude/rules/task-tracking.md`, `.claude/rules/platform.md`, `.claude/rules/error-handling.md`, `.claude/rules/docs.md`, `.claude/rules/execution.md`, `.claude/rules/observability.md`
- One script: `.claude/scripts/statusline-command.js`

---

## File Reference

| File                            | When You Edit It                                                    |
| ------------------------------- | ------------------------------------------------------------------- |
| `operations/src/index.ts`       | Adding or removing resources                                        |
| `operations/src/<domain>/*.ts`  | Writing and modifying workflow logic (organized by business domain) |
| `docs/index.md`                 | Updating project documentation                                      |
| `docs/resources.md`             | Never -- auto-generated by `/deploy` and `/elevasis deploy`         |
| `operations/elevasis.config.ts` | Changing project-level settings                                     |
| `.env`                          | Adding environment variables                                        |
| `CLAUDE.md`                     | Rarely -- only to add project-specific context                      |
| `.claude/skills/*/SKILL.md`     | Rarely -- skills work well as scaffolded                            |

---

**Last Updated:** 2026-04-17
