Turn a README into an Architecture Diagram

What you'll build

In this tutorial, you will take an existing project README.md containing a Mermaid flowchart and text descriptions, parse it locally inside Rekhic, and transform it into an editable, styled architecture diagram on your infinite canvas.

Before you start

• Have a markdown README file or text snippet with architecture details or a Mermaid diagram.
• If you don't have one handy, Rekhic provides a built-in Load Sample button inside the generator.

Step 1: Open the README Generator

1. In the top navigation bar or Dashboard, navigate to Generators -> README (/import/readme).
2. You will see an input editor with options to paste text, upload a .md file, or load a sample.

Step 2: Input Your README Content

1. Paste your markdown content into the editor, or click Load Sample to inspect a pre-populated microservices architecture example:

markdown Copy
# E-Commerce Platform

## Architecture
```mermaid
graph TD
  Client[Web Client] --> Gateway[API Gateway]
  Gateway --> OrderService[Order Service]
  Gateway --> CatalogService[Catalog Service]
  OrderService --> OrderDB[(PostgreSQL)]
  CatalogService --> Cache[(Redis Cache)]

Technologies

• Next.js, Node.js, PostgreSQL, Redis, Docker

---

## Step 3: Run the Analysis

1. Click the **Analyze README** button.
2. In milliseconds, Rekhic's local parser extracts:
   - Component nodes from the Mermaid graph (`Web Client`, `API Gateway`, `Order Service`, `Catalog Service`).
   - Data stores (`PostgreSQL`, `Redis Cache`).
   - Directional relationships and flowpaths.
   - Technology tags from the markdown text.

---

## Review the generated architecture

In the **Architecture Preview** panel on the right:
- Verify that all services and databases were detected.
- Check the **Components**, **Data Stores**, and **Relationships** summary counts.
- Inspect the visual topology card.

---

## Customize the diagram

1. Click **Open in Canvas**.
2. A new Rekhic workspace opens with your imported architecture laid out cleanly.
3. Select the `PostgreSQL` node and open the **Icon Picker** to ensure the official PostgreSQL logo is applied.
4. Reposition or space out nodes to your preference, or click **Auto Layout** to balance vertical and horizontal spacing.
5. Add text notes or sticky notes for any edge cases not captured in the original README.

---

## Export your result

1. Click **Export** in the header bar and download an updated **PNG** or **SVG** image.
2. Replace the static text or old diagram in your project repository with the new visual graphic.
3. Click **Export Markdown** to generate a companion `ARCHITECTURE.md` file.

---

## Tips

- If your README contains multiple Mermaid diagrams, Rekhic will merge and harmonize the topologies.
- Ensure component names inside Mermaid brackets are descriptive (e.g. `OrderService[Order Service]` rather than ambiguous IDs like `A[A]`).

---

## Limitations

- Rekhic supports `graph TD`, `graph TB`, `graph LR`, `flowchart TD`, and `flowchart LR`. Sequence diagrams and state machine diagrams are not currently converted to architecture topologies.
- Analysis is 100% client-side and deterministic; highly unconventional or unstructured text without headings may require manual node placement.