MapCraft overview
MapCraft is where a SourceProfile (or any source schema) is turned
into a governed transformation Project. You define how each target field is
populated, codify reusable rules and lookups, version your work, and
compile a DAG that FlowBridge can run.
Where StructScan answers "what is this data?", MapCraft answers "what should it become, and exactly how?".
What you can do
- Create a Project that ties together a source schema, a target schema, and (optionally) a source profile from StructScan.
- Upload schemas (CSV, JSON, or XSD) — MapCraft parses them into a canonical internal shape.
- Auto-map source fields to target fields with confidence scores; accept, reject, or override.
- Write transformation rules in natural language — MapCraft generates Python, SQL, and JSONata for each rule.
- Manage lookup tables for reference data (country codes, currency codes, status enums, …).
- Save versions with change summaries; diff and restore any past version.
- Compile a DAG from confirmed mappings — the DAGDocument is the artifact FlowBridge runs.
- Export the project as JSON config or as a standalone Python module.
Project lifecycle
A new Project starts in DRAFT. The moment you create the first mapping it
moves to MAPPING. When you mark mappings as ready for review (or hand the
project to a reviewer), it moves to REVIEW. Once mappings are confirmed
and a DAG is compiled, it moves to COMPLETE. ARCHIVED is a soft-delete
that hides the project from default views without losing history.
Three views of a Project
Every Project opens at /mapcraft/{projectId} with a view switcher.
- Canvas
- Table
- DAG
The Canvas is the visual mapping surface. Source fields on the left, target fields on the right, lines between them. Best when you are drawing the first mappings, when a field has a non-trivial rule, or when you want to explain a mapping in a screenshare.
The Table view shows every mapping field as one row: source path, target path, status, confidence, rule, lookup. Best when you have hundreds of fields and want to bulk-accept the AI suggestions, filter by status, or search by name.
The DAG view is the compiled representation. Each node is a stage (extract, transform, load, deliver); each node has a previewable SQL plan. You compile to this view from confirmed mappings — it is not editable directly. Use it to verify the shape of the pipeline before handing it to FlowBridge.
Core concepts
| Concept | What it is |
|---|---|
Project | The top-level container. Has a name, status, lane, source schema, target schema, and (optionally) a source profile reference. |
Schema | A canonical representation of a source or target shape. Stored as canonical_fields — a list of typed paths. |
Mapping | A named grouping of MappingFields under a Project. Most projects have one Mapping; complex projects may have several. |
MappingField | One source-path → target-path pair, with a status, confidence, and optional rule and lookup references. |
TransformationRule | A named transformation defined in natural language, with generated Python / SQL / JSONata. Attaches to a MappingField. |
LookupTable | A two-column key/value reference table (e.g. country_name → country_code). Attaches to a MappingField via its rule. |
Version | A snapshot of the Project — fields, rules, lookups — with a change summary. |
MappingField statuses
- UNMAPPED — no source field is wired to this target field yet.
- AI_SUGGESTED — MapCraft proposed a source field; awaiting your call.
- ACCEPTED — confirmed; included in compile.
- REJECTED — explicitly dismissed; will not be included.
- MANUAL — you wired it directly without an AI suggestion.
Only ACCEPTED and MANUAL fields are included when the DAG is compiled.
Lanes
A Project's lane controls what kind of DAG can be compiled from it.
- Warehouse
- Document
- Both
Use when you are loading or transforming inside a SQL warehouse (Postgres, Snowflake). The compiled DAG produces SQL statements and uses the Extract & Load surface in FlowBridge.
Use when you are producing a document drop — JSON, XML, EDI, HL7 v2 — delivered via SFTP / HTTP / file / webhook. The compiled DAG produces an in-memory transformation plus a delivery node.
Use when the same project must populate a warehouse table and drop a document to a partner from the same confirmed mappings. The compiled DAG forks into both lanes.
Where to go next
- Hands-on tutorial: MapCraft walkthrough — pick up the project created at the end of the StructScan walkthrough and drive it to a compiled DAG.
- Previous stage: StructScan overview.
- Next stage: FlowBridge overview.