How ms111134zg-jpg/task_manegement_portfolio works
プロジェクトの種類と目的(この前提で図を作る)
これは FastAPI + PostgreSQL(async SQLAlchemy) の タスク管理API(MVP) です。
READMEは「Phase1 / API Only」と書いていますが、リポジトリには frontend/(静的HTML/JS)も同梱されています。従って、図は 「APIが主」、ただし 「同梱フロントは別コンテナ(または将来連携)」 として描くのが最も正確です。
実装機能の中心は:
• Users / Tasks の CRUD
• Tasks 一覧の検索・フィルタ・ソート・ページング
• Stats(status別件数集計)
• 例外・DB制約エラーのマッピング(409/400等)
• Swagger UI(/docs)で動作確認
Backend(FastAPIアプリの中核)
• backend/app/main.py
→ FastAPI app 作成、ルーティング登録、ミドルウェア/例外ハンドラ登録(推定)
• backend/app/db.py
→ Async SQLAlchemy のエンジン/Session管理、DB接続
• backend/app/settings.py
→ pydantic-settings で .env 読み込み(DB接続設定)
• backend/app/models/*
→ SQLAlchemy ORMモデル(user.py, task.py, base.py)
• backend/app/schema_pydantic/*
→ 入出力DTO(Pydantic schema:user.py, task.py, stats.py)
• backend/app/crud/*
→ DBアクセス・クエリ組み立て(タスク一覧のfilter/sort/pagingなどの中心)
• backend/app/errors.py
→ DB制約違反(SQLSTATE)などをHTTPエラーに変換する責務
> ここから、このAPIは典型的な「FastAPI(ルート)→ CRUD層 → ORM/DB」というレイヤに分解できます。
> もしルータファイルが見当たらない場合でも、main.py がエンドポイントを直接持つか、内部で import しているはずなので、図では「API Routes(FastAPI)」というコンポーネントとして表現すれば十分正確です。
• db/schema.sql / db/seed.sql
→ DB初期化(DDL/seed)。運用・セットアップの“データプレーン外”の要素として図に入れる価値があります(後述)。
Frontend(静的クライアント、同梱)
• frontend/index.html + frontend/js/infra/api.js + frontend/js/pages/*
→ REST API を叩く薄いクライアント。READMEはAPI Onlyだが、実体としては「別デプロイ可能な静的サイト」として描けます。
READMEから図に必ず反映すべき「重要な性質」
• DBは PostgreSQL
• DBアクセスは async SQLAlchemy + asyncpg
• .env で設定注入(pydantic-settings)
• エンドポイント群:
• /health, /health/db
• /api/users ...
• /api/tasks ...(一覧パラメータ豊富)
• /api/stats/tasks-by-status
• エラーハンドリング方針(SQLSTATE→HTTPコード変換)
• Swagger UI(/docs)が主要な利用UI(開発・検証)
「最も正確なシステム設計図」を描く手順(このプロジェクト向け)
Principal向けには C4モデル風に 3枚(Context / Container / Component) を作るのが、情報密度と誤解の少なさのバランスが良いです。加えて、必要なら「Deployment/Runtime」を1枚足します。
登場要素(最小)
• Actor: API利用者(開発者 / Swagger UI利用者)
• Actor: ブラウザ(Swagger UI / 同梱フロント)
• System: Task Management API(FastAPI)
• System: PostgreSQL
矢印(必須)
• Browser → FastAPI API(HTTPS/HTTP, REST)
• FastAPI → PostgreSQL(asyncpg)
> READMEの「/docs」重視に合わせて、「Swagger UI(OpenAPI)」を Browser 内要素として明示すると正確です。
Container 図(実行単位・デプロイ単位)
このプロジェクトは少なくとも以下のコンテナ/プロセスとして描けます:
Web Client(Browser)
• Swagger UI(FastAPIが提供)
• (任意)Static Frontend(frontend/。別ホストでも同一ホストでも可)
API Server
• Uvicorn + FastAPI(uvicorn backend.app.main:app)
• 内部に「Routing」「Validation」「Error handling」「DB session」などを含む
Database
• PostgreSQL(schema/seedで初期化)
Config
• .env(SettingsとしてAPI Serverに注入)
矢印(推奨ラベル)
• Browser → API Server: REST / JSON
• API Server → DB: SQL (async SQLAlchemy via asyncpg)
• .env → API Server: Pydantic Settings
“同梱フロント”の扱い(正確さを担保する描き分け)
• README準拠なら:Frontendは「Phase2候補」として 点線 や Optional ラベルで示す
• 実態準拠なら:Frontendを「Static site」コンテナとして描き、frontend/js/infra/api.js が API を呼ぶ矢印を入れる
Component 図(backend/app 内の主要コンポーネント)
ここが一番「詳細に分ける」価値があります。ファイル構造がそのままコンポーネント境界として使えます。
API Layer(FastAPI)
• FastAPI App / Routes(backend/app/main.py)
• Health endpoints
• Users endpoints
• Tasks endpoints
• Stats endpoints
• Request/Response Validation(Pydantic schema)
• schema_pydantic/user.py
• schema_pydantic/task.py
• schema_pydantic/stats.py
矢印
• Routes → CRUD(ユースケース/永続化操作を委譲)
• Routes → Errors(例外ハンドリング/変換)
• Routes → DB session provider(依存性注入があれば)
Domain/Data Access(CRUD)
• crud/user.py
• crud/task.py
• タスク一覧の「検索・フィルタ・ソート・ページング」ロジックはここが中心になりやすいので、
“Task Query Builder” 的に一段細かいサブコンポーネントとして描くのも良いです(principal向けに価値が高い)。
矢印
• CRUD → SQLAlchemy Models
• CRUD → Async Session/DB
Persistence Model(ORM)
• models/base.py(Declarative Base等)
• models/user.py
• models/task.py
矢印
• Models ↔ PostgreSQL(テーブル users/tasks)
Infrastructure
• db.py(Async Engine / Session / connection)
• settings.py(環境変数→設定)
• errors.py(SQLSTATE判定→HTTP例外)
矢印
• Settings → DB(接続文字列/host/port/etc)
• DB → CRUD/Routes(Session提供)
• Errors ← CRUD/DB例外(例: unique_violation 23505 → 409)
(任意)Runtime / Initialization 図(セットアップと起動経路)
このプロジェクトは「運用手順が明示」されているので、1枚追加すると理解が早いです。
• db/schema.sql → PostgreSQL(DDL適用)
• db/seed.sql → PostgreSQL(初期データ投入)
• uvicorn backend.app.main:app → API起動
• 起動後:/docs(Swagger UI)→ API呼び出し → DB
> ここは“データフロー”ではなく“オペレーションフロー”なので、色やスイムレーンで区別すると誤解が減ります。
タスク一覧(検索・フィルタ・ソート・ページング)
• 図の中で Tasks List Endpoint から Task CRUD(Query Builder) に矢印を出し、
その横にパラメータ(q/status/user_id/due_from/due_to/sort/order/limit/offset)を注記してください。
• Principal視点だと、ここが性能/複雑性の焦点なので、「クエリ組み立て責務」を独立して見せるのが有効です。
Stats(集計)
• GET /api/stats/tasks-by-status は「tasksテーブルをgroup by」するはずなので、
Stats endpoint → CRUD(Stats) → DB の流れを明示(CRUDが task.py に含まれていてもコンポーネント上は分けてOK)。
エラー変換(SQLSTATE → HTTP)
• errors.py を「例外マッピング」コンポーネントとして描き、
DB例外がどこで捕捉され、どうHTTPへ変換されるか(409/400/404/422)を矢印で表現すると設計の意図が伝わります。
図の表現ルール(principal向けに“正確で詳細”にする)
最低限、以下を徹底してください:
• ラベル
• コンポーネント名(例:FastAPI Routes, Task CRUD, Async SQLAlchemy Session, PostgreSQL)
• プロトコル/形式(HTTP/JSON, SQL, OpenAPI/Swagger UI)
• 方向付き矢印
• 「呼び出し方向(依存方向)」と「データの流れ」を一致させる
• 色/形の使い分け(おすすめ)
• 青: Presentation(Browser/Swagger/Frontend)
• 緑: API(FastAPI Routes / Pydantic)
• 黄: Domain/Data Access(CRUD)
• 赤: Infrastructure(DB/session/settings/error mapping)
• 灰: Data Store(PostgreSQL)
• Optional/Phase表現
• frontend/ は README と整合させるなら点線枠 + “Optional/Phase2” 注記
最後に:このリポジトリから「部品を最大限に分ける」具体例(そのまま図の箱にできる)
• Client
• Swagger UI (/docs)
• (Optional) Static Frontend (HTML/JS)
• API Server (Uvicorn)
• FastAPI App (main.py)
• Health Controller
• Users Controller
• Tasks Controller
• Stats Controller
• Pydantic Schemas (schema_pydantic/*)
• Error Mapping (errors.py)
• Settings (settings.py)
• DB Session/Engine (db.py)
• CRUD: User (crud/user.py)
• CRUD: Task (crud/task.py)
• ORM Models (models/*)
• Database
• PostgreSQL
• DDL (db/schema.sql)
• Seed (db/seed.sql)
この粒度で箱を切って矢印を全部つなぐと、過不足なく「最も詳細で正確」なアーキテクチャ図になります(特にprincipalレビューで突っ込まれやすい、設定注入・例外変換・クエリ複雑性が可視化されます)。