Skip to main content

Project Structure

InstaCRUD is organized into backend and frontend directories with supporting tooling.

Repository Root​

instacrud/
├── backend/             # Python API server
├── frontend/            # Next.js admin UI
├── bruno/               # API testing workspace
├── docker-compose.yml   # Stack orchestration
├── README.md
└── LICENSE

Backend (Python)​

backend/
├── instacrud/           # Main application package
│   ├── ai/              # AI services (completion, embedding, vision, MCP)
│   ├── api/             # REST endpoints and DTOs
│   ├── mailer/          # Email services (Brevo, file-based)
│   │   └── templates/   # Email templates (HTML/TXT)
│   └── model/           # Data models (organization, system)
├── init/                # DB initialization and migration scripts
├── test/                # Test suite
├── static/              # Static file serving
├── pyproject.toml       # Poetry dependencies
└── Dockerfile

Key backend modules:

  • ai/ — LLM completion, embeddings, vision, vector search, MCP client
  • api/ — Organization, system, OAuth, calendar, AI endpoints
  • mailer/ — Email delivery with Brevo integration
  • model/ — Pydantic models for organizations and system entities

Run backend:

poetry run python instacrud/app.py

Frontend (Next.js)​

frontend/
├── src/
│   ├── api/             # Generated API client
│   │   ├── core/        # HTTP client infrastructure
│   │   ├── models/      # TypeScript types
│   │   └── services/    # Service classes
│   └── app/             # Next.js App Router
│       └── (admin)/
│           ├── (entities)/      # CRUD views
│           │   ├── addresses/
│           │   ├── aimodels/
│           │   ├── clients/
│           │   ├── contacts/
│           │   ├── documents/
│           │   ├── invitations/
│           │   ├── organizations/
│           │   ├── projects/
│           │   ├── tiers/
│           │   └── users/
│           └── (others-pages)/  # Utility pages
│               └── ai-assistant/
├── public/              # Static assets
├── scripts/             # Build utilities
├── package.json
└── Dockerfile

Run frontend:

npm run dev

Generate API client from OpenAPI spec:

npm run generate-api

Bruno​

bruno/
├── environments/        # Environment configs
├── admin/               # Admin API requests
├── system/              # System API requests
└── [entity folders]/    # Entity-specific requests

API testing workspace for debugging endpoints during development.

Docker​

Run the full stack:

docker-compose up -d

Services:

  • MongoDB — Database
  • Backend — Python API server
  • Frontend — Next.js application