# ms111134zg-jpg/task_manegement_portfolio architecture

> Architecture diagram of the GitHub repository ms111134zg-jpg/task_manegement_portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ms111134zg-jpg/task_manegement_portfolio
- Repository: https://github.com/ms111134zg-jpg/task_manegement_portfolio

## Overview

##### プロジェクトの種類と目的（この前提で図を作る）
これは **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レビューで突っ込まれやすい、設定注入・例外変換・クエリ複雑性が可視化されます）。

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context / Entry Points
    %% =========================
    Actor["API Consumer (Developer/Test)"]:::external
    Browser["Web Browser"]:::frontend

    subgraph "Client Surface"
        Swagger["Swagger UI (/docs)"]:::frontend
        OptionalNote["Optional/Phase2: Static Frontend (bundled)"]:::note
        subgraph "Static Frontend (Optional)"
            FEIndex["index.html (Entry)"]:::frontend
            FEStyles["CSS Styling"]:::frontend
            FEApiClient["JS API Client (REST)"]:::frontend
            subgraph "Pages (HTML/JS)"
                FEPagesDir["pages/ (Task CRUD JS)"]:::frontend
                FENew["task_new.html"]:::frontend
                FEUpdate["task_update.html"]:::frontend
                FEDetail["task_detail.html"]:::frontend
                FEDelete["task_delete.html"]:::frontend
            end
        end
    end

    %% =========================
    %% Container: API Server
    %% =========================
    subgraph "API Server Container (Uvicorn + FastAPI)"
        Routes["FastAPI App / Routes"]:::api

        subgraph "Controllers (Endpoints)"
            Health["Health Controller (/health, /health/db)"]:::api
            UsersCtl["Users Controller (/api/users)"]:::api
            TasksCtl["Tasks Controller (/api/tasks)"]:::api
            StatsCtl["Stats Controller (/api/stats/tasks-by-status)"]:::api
        end

        subgraph "Validation (Pydantic Schemas)"
            UserDTO["User DTO Schemas"]:::api
            TaskDTO["Task DTO Schemas"]:::api
            StatsDTO["Stats DTO Schemas"]:::api
        end

        subgraph "Data Access Layer (CRUD)"
            UserCRUD["User CRUD"]:::domain
            TaskCRUD["Task CRUD"]:::domain
            TaskQueryBuilder["Task Query Builder\n(filter/sort/paging)"]:::domain
            StatsQuery["Stats Query (group by status)"]:::domain
        end

        subgraph "Persistence Model (SQLAlchemy ORM)"
            ORMBase["Declarative Base"]:::domain
            ORMUser["User Model"]:::domain
            ORMTask["Task Model"]:::domain
        end

        subgraph "Infrastructure"
            Settings["Settings (.env via pydantic-settings)"]:::infra
            DBSession["Async SQLAlchemy Engine/Session\n(asyncpg)"]:::infra
            ErrorMap["Error Mapping\n(SQLSTATE -> HTTP 409/400/etc)"]:::infra
        end
    end

    %% =========================
    %% Container: Database
    %% =========================
    subgraph "Database Container"
        Postgres[("PostgreSQL")]:::datastore
        subgraph "DB Initialization (Ops)"
            DDL["schema.sql (DDL)"]:::ops
            Seed["seed.sql (Seed Data)"]:::ops
        end
    end

    %% =========================
    %% Relationships (Vertical)
    %% =========================
    Actor -->|"uses"| Browser
    Browser -->|"OpenAPI/Swagger UI"| Swagger
    Swagger -->|"HTTP/JSON"| Routes

    OptionalNote -.->|"served/deployed separately"| FEIndex
    FEIndex -->|"loads"| FEApiClient
    FEIndex -->|"loads"| FEStyles
    FEIndex -->|"navigates"| FENew
    FEIndex -->|"navigates"| FEUpdate
    FEIndex -->|"navigates"| FEDetail
    FEIndex -->|"navigates"| FEDelete
    FEPagesDir -->|"used by"| FEApiClient
    FEApiClient -.->|"HTTP/JSON (REST)"| Routes

    Routes -->|"routes to"| Health
    Routes -->|"routes to"| UsersCtl
    Routes -->|"routes to"| TasksCtl
    Routes -->|"routes to"| StatsCtl

    Health -->|"uses"| DBSession
    Health -->|"checks"| Postgres

    UsersCtl -->|"validate"| UserDTO
    UsersCtl -->|"calls"| UserCRUD

    TasksCtl -->|"validate"| TaskDTO
    TasksCtl -->|"calls"| TaskCRUD
    TasksCtl -->|"list params: q/status/user_id/due_from/due_to/sort/order/limit/offset"| TaskQueryBuilder

    StatsCtl -->|"validate"| StatsDTO
    StatsCtl -->|"calls"| StatsQuery

    UserCRUD -->|"uses session"| DBSession
    TaskCRUD -->|"uses session"| DBSession
    TaskQueryBuilder -->|"builds query for"| TaskCRUD
    StatsQuery -->|"uses session"| DBSession

    UserCRUD -->|"maps to"| ORMUser
    TaskCRUD -->|"maps to"| ORMTask
    ORMUser -->|"extends"| ORMBase
    ORMTask -->|"extends"| ORMBase

    DBSession -->|"SQL (async SQLAlchemy via asyncpg)"| Postgres

    Settings -->|"configures"| DBSession
    Settings -->|"injects DB URL"| DBSession

    DBSession -->|"raises DB errors"| ErrorMap
    UserCRUD -->|"DB exceptions"| ErrorMap
    TaskCRUD -->|"DB exceptions"| ErrorMap
    ErrorMap -->|"HTTP errors"| Routes

    DDL -->|"apply DDL"| Postgres
    Seed -->|"insert seed"| Postgres

    %% =========================
    %% Click Events (paths only)
    %% =========================
    click Routes "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/main.py"
    click DBSession "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/db.py"
    click Settings "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/settings.py"
    click ErrorMap "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/errors.py"
    click UserCRUD "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/crud/user.py"
    click TaskCRUD "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/crud/task.py"
    click ORMBase "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/models/base.py"
    click ORMUser "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/models/user.py"
    click ORMTask "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/models/task.py"
    click UserDTO "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/schema_pydantic/user.py"
    click TaskDTO "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/schema_pydantic/task.py"
    click StatsDTO "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/backend/app/schema_pydantic/stats.py"
    click DDL "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/db/schema.sql"
    click Seed "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/db/seed.sql"
    click FEIndex "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/index.html"
    click FEApiClient "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/js/infra/api.js"
    click FEPagesDir "https://github.com/ms111134zg-jpg/task_manegement_portfolio/tree/main/frontend/js/pages/"
    click FENew "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/task_new.html"
    click FEUpdate "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/task_update.html"
    click FEDetail "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/task_detail.html"
    click FEDelete "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/task_delete.html"
    click FEStyles "https://github.com/ms111134zg-jpg/task_manegement_portfolio/blob/main/frontend/css/style.css"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E6E6E6,stroke:#666,stroke-width:1px,color:#111
    classDef frontend fill:#D7EBFF,stroke:#2B6CB0,stroke-width:1px,color:#0B2545
    classDef api fill:#D8F5D2,stroke:#2F855A,stroke-width:1px,color:#123
    classDef domain fill:#FFF2B8,stroke:#B7791F,stroke-width:1px,color:#3B2F00
    classDef infra fill:#FFD6D6,stroke:#C53030,stroke-width:1px,color:#3B0A0A
    classDef datastore fill:#D9D9D9,stroke:#4A5568,stroke-width:1px,color:#111
    classDef ops fill:#EFEFEF,stroke:#718096,stroke-dasharray:4 3,stroke-width:1px,color:#111
    classDef note fill:#FFF,stroke:#666,stroke-dasharray:5 4,color:#111
```
