🏗️ mkarchi

Design your architecture once, apply it anywhere

Documentation • Latest Version • FAQ • Community

---

🌟 What is mkarchi?

mkarchi (make architecture) is a powerful command-line tool that generates complete project structures from simple tree-format text files. With v0.1.7, you can also reverse-engineer your existing projects back into mkarchi format — making project scaffolding and documentation effortless.

---

✨ Key Features

📋 Generation 📁 Create directories from tree structures 📄 Generate files with or without content ✍️ Content embedding using (begincontenu) tags 🎯 Indentation preservation for Python, YAML, JSON 💬 Comments support in structure files

🔄 Reverse Engineering 🔄 Generate mkarchi files from existing projects 🚫 Smart .gitignore integration (NEW v0.1.7) ⚡ Improved performance and error handling 🚀 Fast, simple, and AI-friendly 📦 Reusable templates for any project

---

🚀 Quick Start

Installation

pip install mkarchi

📦 Alternative Installation Methods

Install from source:

git clone https://github.com/SoufyanRachdi/mkarchi.git
cd mkarchi
pip install -e .

Run as module (no installation):

git clone https://github.com/SoufyanRachdi/mkarchi.git
cd mkarchi
python -m mkarchi apply structure.txt

Create Your First Project

1. Create a structure file (structure.txt):

my_project/
├── src/
│   ├── main.py(begincontenu)
│   │   def main():
│   │       print("Hello, World!")
│   │
│   │   if __name__ == "__main__":
│   │       main()
│   (endcontenu)
│   └── utils.py
├── tests/
│   └── test_main.py
├── README.md(begincontenu)
│   # My Project
│
│   This is an awesome project!
│   (endcontenu)
└── requirements.txt(begincontenu)
    pytest>=7.0.0
    requests>=2.28.0
(endcontenu)

2. Apply the structure:

mkarchi apply structure.txt

3. See the magic ✨

🚀 Creating structure from structure.txt...

📁 Created directory: my_project
📁 Created directory: my_project/src
📄 Created file with content: my_project/src/main.py
📄 Created file: my_project/src/utils.py
📁 Created directory: my_project/tests
📄 Created file: my_project/tests/test_main.py
📄 Created file with content: my_project/README.md
📄 Created file with content: my_project/requirements.txt

✅ Architecture created successfully!

---

📖 Commands

# Apply a structure file to create project
mkarchi apply structure.txt

# Generate structure file from current directory
mkarchi give

# Generate without file contents
mkarchi give -c

# Save to custom file
mkarchi give myproject.txt

# Get help
mkarchi --help

# Check version
mkarchi --version

---

🔄 Reverse Engineering with mkarchi give

Generate mkarchi syntax from your existing project structure.

Default Behavior

mkarchi give

✅ Generates structure.txt
✅ Includes file contents
✅ Respects .gitignore automatically

Without File Contents

mkarchi give -c

Custom Output File

mkarchi give -c myproject.txt

🚫 Smart .gitignore Integration (v0.1.7)

mkarchi automatically reads your .gitignore and excludes:

• node_modules/, venv/, __pycache__/
• .git/ directories
• Build artifacts and cache files
• Binary files and dependencies

Example .gitignore:

node_modules/
*.pyc
__pycache__/
.env

Running mkarchi give automatically skips all these files! 🎉

---

📝 Structure File Syntax

Directories

Directories must end with /:

my_folder/
├── subfolder/
└── another_folder/

Empty Files

Files without content tags are created empty:

my_folder/
├── empty_file.txt
└── config.json

Files with Content

Use (begincontenu) and (endcontenu):

script.py(begincontenu)
    def hello():
        print("Hello, World!")
(endcontenu)

Indentation Preservation

Indentation is automatically preserved:

utils.py(begincontenu)
    def greet(name):
        if name:
            print(f"Hello, {name}!")
        else:
            print("Hello, World!")
(endcontenu)

Result (utils.py):

def greet(name):
    if name:
        print(f"Hello, {name}!")
    else:
        print("Hello, World!")

Comments

Use # for comments:

project/
├── src/          # Source code
│   └── main.py   # Entry point
└── tests/        # Tests

---

🎯 Use Cases

⚡ Rapid Scaffolding Spin up new projects in seconds with predefined templates.	🤖 AI Integration Perfect for AI-generated project structures and code scaffolding.	📦 Reusable Templates Create once, reuse everywhere. Share templates with your team.
🧩 Microservices Set up multiple services with consistent structure: mkarchi apply service1.txt mkarchi apply service2.txt	📘 Documentation Generate clean project documentation: mkarchi give docs.txt	🎓 Tutorials Create step-by-step project structures for teaching and learning.

---

🔧 Advanced Example: Python Project

python_project/
├── src/
│   ├── __init__.py
│   ├── main.py(begincontenu)
│   │   """Main application module."""
│   │
│   │   def main():
│   │       print("Starting application...")
│   │       return 0
│   │
│   │   if __name__ == "__main__":
│   │       main()
│   (endcontenu)
│   └── config.py(begincontenu)
│       """Configuration module."""
│   
│       DEBUG = True
│       VERSION = "0.1.0"
│   (endcontenu)
├── tests/
│   ├── __init__.py
│   └── test_main.py(begincontenu)
│       import pytest
│       from src.main import main
│
│       def test_main():
│           """Test main function."""
│           assert main() == 0
│   (endcontenu)
├── .gitignore(begincontenu)
│   __pycache__/
│   *.pyc
│   .pytest_cache/
│   venv/
│   (endcontenu)
├── setup.py(begincontenu)
│   from setuptools import setup, find_packages
│
│   setup(
│       name="my-project",
│       version="0.1.0",
│       packages=find_packages(),
│       install_requires=[
│           "pytest>=7.0.0",
│       ],
│   )
│   (endcontenu)
└── README.md(begincontenu)
    # Python Project
    
    A well-structured Python project template.
(endcontenu)

---

🆕 What's New in v0.1.7?

🚫 .gitignore Support Automatically respects .gitignore patterns

⚡ Performance Boost Faster processing and optimized traversal

🐛 Bug Fixes Enhanced error handling and Unicode support

View full changelog →

Learn more about v0.1.7 →

---

📚 Documentation & Resources

Resource	Description
📖 Documentation	Complete guide and tutorials
🔄 Version History	All releases and updates
📘 v0.1.7 Guide	Latest version features
📗 v0.1.6 Guide	Previous version features
❓ FAQ	Frequently asked questions
👥 Community	Join the community
📧 Contact	Get in touch

---

🤝 Contributing

Contributions are welcome! We appreciate your help in making mkarchi better.

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m "Add amazing feature"

4. Push to your branch

   git push origin feature/amazing-feature

5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

🐛 Issues & Support

Found a bug or have a feature request?

• 🐛 Report an issue
• 💬 Join our community
• 📧 Contact us

---

⭐ Star Us!

If you find mkarchi useful, please consider giving it a ⭐ on GitHub!

---

Made with ❤️ by Soufyan Rachdi

Documentation • Community • Contact