fastapi-domain-monitor 0.1.19

FastAPI plugin for real-time SQLModel domain diagram visualization

fastapi-domain-monitor

Real-time Mermaid classDiagram monitoring for Pydantic and SQLModel projects running on FastAPI.

• Mount directly inside an existing FastAPI app
• Rebuild diagrams automatically when model files change
• Support compact and full detail modes
• Show classes, enums, inheritance, relationships, notes, and source excerpts

Table Of Contents

English

1. Overview
2. Installation
3. Quick Start
4. Recommended Project Layout
5. FastAPI Integration Options
6. Standalone Mode
7. Local Development Notes
8. Diagram-Friendly Modeling

한국어

1. 소개
2. 설치
3. 빠른 시작
4. 권장 프로젝트 구조
5. FastAPI 연동 옵션
6. 단독 실행 모드
7. 로컬 개발 시 주의사항
8. 다이어그램 친화적인 모델 작성 규칙

---

English

Overview

fastapi-domain-monitor is a development tool that parses Python source code with AST and renders a live Mermaid classDiagram for your Pydantic and SQLModel classes.

It is designed for projects where you want to:

• inspect domain models while coding
• follow schema changes in real time
• expose a browser-based class diagram inside your FastAPI app
• review relationships, inheritance, defaults, notes, and source excerpts quickly

Installation

Install from PyPI with uv

uv add fastapi-domain-monitor

Install from PyPI with pip

pip install fastapi-domain-monitor

Install from a local checkout in editable mode

This is useful when you are developing the library and your app together.

uv add --editable /path/to/fastapi-domain-monitor

or

pip install -e /path/to/fastapi-domain-monitor

Quick Start

Add the monitor to your FastAPI app:

from fastapi import FastAPI
from fastapi_domain_monitor import setup_domain_monitor

app = FastAPI()

setup_domain_monitor(
    app,
    watch_dirs=["src/modules"],
)

Run your app:

uv run uvicorn src.main:app --reload

Open:

http://127.0.0.1:8000/domain-monitor

Recommended Project Layout

By default, the monitor watches these file patterns:

*_models.py
models.py
*_schemas.py
schemas.py
*_entities.py
entities.py
*_dto.py
dto.py

Example:

src/
  modules/
    accounts/
      models.py
    exams/
      schemas.py
    billing/
      dto.py

FastAPI Integration Options

from fastapi import FastAPI
from fastapi_domain_monitor import setup_domain_monitor

app = FastAPI()

setup_domain_monitor(
    app,
    watch_dirs=["src/modules", "src/domains"],
    watch_patterns=["models.py", "schemas.py", "dto.py"],
    mount_path="/domain-monitor",
    detail_level="compact",   # "compact" | "full"
    show_base_fields=False,
    enabled=True,
)

Important options:

• watch_dirs: root directories to scan
• watch_patterns: file globs to parse
• mount_path: dashboard path, default is /domain-monitor
• detail_level: compact or full
• show_base_fields: show common fields like id, created_at
• enabled: easy environment-based switch

Standalone Mode

You can also run the monitor as a separate local server:

domain-monitor start -w src/modules

Example with more options:

domain-monitor start \
  -w src/modules \
  --watch-pattern models.py \
  --watch-pattern schemas.py \
  --detail-level full \
  --show-base-fields \
  --port 7842

Open:

http://127.0.0.1:7842/domain-monitor

Local Development Notes

• This package is intended for development-time visualization.
• uvicorn --reload usually watches only your application directory.
• If you install this package as an editable local dependency and modify the library itself, your app server may need a restart before changes appear.

Diagram-Friendly Modeling

If you want the diagram to reflect your code reliably, keep the model structure visible in static source.

• Put models in watched files such as *_models.py, models.py, *_schemas.py, schemas.py, *_entities.py, entities.py, *_dto.py, and dto.py.
• Declare ORM relationships with Relationship(...).
• Prefer direct type annotations for nested models and enums, for example status: ExamStatus and items: list[LineItem].
• If an enum-backed field must stay str, expose the enum statically with one of these patterns:
  • status: str = Field(default=ExamStatus.DRAFT)
  • sa_column=Column(SAEnum(ExamStatus, ...))
  • status: str # ExamStatus
  • return self.status == ExamStatus.DRAFT
• Keep table=True, __tablename__, model_config, and ConfigDict in the class body instead of building them dynamically.
• Avoid runtime-only schema generation patterns if diagram fidelity matters.

Links

• PyPI: fastapi-domain-monitor
• Repository: ureca-corp/fastapi-domain-monitor

---

한국어

소개

fastapi-domain-monitor는 Python 소스를 AST로 파싱해서 Pydantic / SQLModel 클래스를 실시간 Mermaid classDiagram으로 보여주는 개발용 도구입니다.

이런 경우에 적합합니다.

• 도메인 모델 구조를 브라우저에서 바로 확인하고 싶을 때
• 모델 파일 변경이 다이어그램에 즉시 반영되길 원할 때
• FastAPI 앱 내부에 다이어그램 대시보드를 붙이고 싶을 때
• 관계선, 상속, 기본값, note, 소스 코드를 빠르게 확인하고 싶을 때

설치

PyPI에서 uv로 설치

uv add fastapi-domain-monitor

PyPI에서 pip로 설치

pip install fastapi-domain-monitor

로컬 소스를 editable 모드로 설치

라이브러리와 사용하는 앱을 동시에 개발할 때 편합니다.

uv add --editable /path/to/fastapi-domain-monitor

또는

pip install -e /path/to/fastapi-domain-monitor

빠른 시작

FastAPI 앱에 setup_domain_monitor()를 붙입니다.

from fastapi import FastAPI
from fastapi_domain_monitor import setup_domain_monitor

app = FastAPI()

setup_domain_monitor(
    app,
    watch_dirs=["src/modules"],
)

앱을 실행합니다.

uv run uvicorn src.main:app --reload

브라우저에서 접속합니다.

http://127.0.0.1:8000/domain-monitor

권장 프로젝트 구조

기본 감시 패턴은 아래와 같습니다.

*_models.py
models.py
*_schemas.py
schemas.py
*_entities.py
entities.py
*_dto.py
dto.py

예시:

src/
  modules/
    accounts/
      models.py
    exams/
      schemas.py
    billing/
      dto.py

FastAPI 연동 옵션

from fastapi import FastAPI
from fastapi_domain_monitor import setup_domain_monitor

app = FastAPI()

setup_domain_monitor(
    app,
    watch_dirs=["src/modules", "src/domains"],
    watch_patterns=["models.py", "schemas.py", "dto.py"],
    mount_path="/domain-monitor",
    detail_level="compact",   # "compact" | "full"
    show_base_fields=False,
    enabled=True,
)

주요 옵션:

• watch_dirs: 감시할 루트 디렉터리 목록
• watch_patterns: 파싱할 파일 패턴 목록
• mount_path: 대시보드 경로, 기본값은 /domain-monitor
• detail_level: compact 또는 full
• show_base_fields: id, created_at 같은 공통 필드 표시 여부
• enabled: 환경별 on/off 스위치

단독 실행 모드

앱 내부에 마운트하지 않고 모니터만 따로 띄울 수도 있습니다.

domain-monitor start -w src/modules

옵션 예시:

domain-monitor start \
  -w src/modules \
  --watch-pattern models.py \
  --watch-pattern schemas.py \
  --detail-level full \
  --show-base-fields \
  --port 7842

접속 주소:

http://127.0.0.1:7842/domain-monitor

로컬 개발 시 주의사항

• 이 패키지는 개발 중 시각화 도구입니다.
• uvicorn --reload는 보통 현재 앱 디렉터리만 감시합니다.
• 이 패키지를 editable 로컬 dependency로 연결해 두고 라이브러리 자체를 수정하는 경우, 앱 서버를 한 번 재시작해야 반영될 수 있습니다.

다이어그램 친화적인 모델 작성 규칙

다이어그램에 코드가 안정적으로 반영되게 하려면, 모델 구조가 정적인 소스 코드 안에 직접 드러나게 작성하는 편이 좋습니다.

• 모델 파일은 *_models.py, models.py, *_schemas.py, schemas.py, *_entities.py, entities.py, *_dto.py, dto.py 같은 감시 패턴 안에 두는 것이 안전합니다.
• ORM 관계는 Relationship(...)로 선언합니다.
• 중첩 모델과 enum은 status: ExamStatus, items: list[LineItem]처럼 타입에 직접 드러내는 것이 가장 안정적입니다.
• enum 기반 필드를 꼭 str로 유지해야 한다면, 아래 중 하나처럼 정적 단서를 남겨야 합니다.
  • status: str = Field(default=ExamStatus.DRAFT)
  • sa_column=Column(SAEnum(ExamStatus, ...))
  • status: str # ExamStatus
  • return self.status == ExamStatus.DRAFT
• table=True, __tablename__, model_config, ConfigDict 같은 메타데이터는 클래스 본문에 명시적으로 둡니다.
• 런타임에만 의미가 드러나는 동적 생성 패턴은 다이어그램 정확도가 떨어질 수 있습니다.

링크

• PyPI: fastapi-domain-monitor
• 저장소: ureca-corp/fastapi-domain-monitor