# karasu-huginn/3proj architecture

> Architecture diagram of the GitHub repository karasu-huginn/3proj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karasu-huginn/3proj
- Repository: https://github.com/karasu-huginn/3proj

## Overview

1. **Repo shape**
   - This is a two-part school project: a **FastAPI backend** in `fastapi/` and a **React + Vite frontend** in `react/`.
   - The overall architecture is a classic client/server split: the frontend renders the UI and calls backend HTTP endpoints; the backend owns business logic, persistence, authentication, and external API access.

2. **Backend entry point and application composition**
   - `fastapi/main.py` is the backend bootstrapping point.
   - The backend is organized around FastAPI routers, with feature-specific modules mounted into the app rather than one large monolith.
   - Shared application concerns live alongside the routers: database setup, models, schemas, auth utilities, and test fixtures.

3. **Persistence and domain model layer**
   - `fastapi/database.py` and `fastapi/db.py` indicate the database connection/session setup is separated from the rest of the app.
   - `fastapi/models.py` and `fastapi/base_models.py` hold the persistent domain entities and common ORM/model abstractions.
   - `fastapi/schemas.py` plus feature-specific `schemas.py` files define request/response shapes, keeping API contracts distinct from persistence objects.

4. **Authentication boundary**
   - Authentication is isolated under `fastapi/auth/`.
   - `router.py` exposes auth endpoints, while `service.py`, `dependencies.py`, and `utils.py` contain the login/session/token logic and FastAPI dependency wiring.
   - This indicates auth is treated as a cross-cutting subsystem: routers consume auth dependencies rather than embedding auth checks directly.

5. **Collections and user library domain**
   - The main business area appears to be **collections/library management**.
   - The backend has dedicated feature routers such as `routers/collections.py`, `routers/users.py`, and `routers/admin.py`.
   - The test suite names (`test_collections_crud.py`, `test_collection_items.py`, `test_collection_status.py`, `test_collections_me.py`) suggest collections support CRUD, item membership, status tracking, and “current user” views.

6. **Media subsystem**
   - Media-specific logic is grouped under `fastapi/routers/media/`.
   - `router.py`, `service.py`, `schemas.py`, and `mangadex.py` show a clear split between HTTP endpoints, business logic, API contracts, and an external media provider adapter.
   - `mangadex.py` is the most explicit external integration in the repo and likely acts as a connector to fetch manga/media metadata.

7. **Social and notifications features**
   - Social interactions are separated into `fastapi/social/` and exposed through `fastapi/routers/social.py`.
   - Notifications are similarly split into `fastapi/notifications/` with router/service/schema layers.
   - This layout implies the backend has multiple domain services, each with its own API surface, rather than one generic “content” module.

8. **Search and admin surfaces**
   - `fastapi/search_router.py` suggests a dedicated search endpoint set, probably spanning multiple domains rather than only collections.
   - `routers/admin.py` plus `tests/test_admin.py` indicates privileged administrative capabilities are isolated from the normal user flows.
   - The presence of a `users` router suggests user-facing profile or account management endpoints separate from auth.

9. **Backend architecture pattern**
   - The naming strongly indicates a layered pattern:
     - **routers** handle HTTP request/response and routing,
     - **services** contain business rules and orchestration,
     - **schemas** define API payloads,
     - **models** represent persisted data,
     - **dependencies/utils** provide auth and shared helpers.
   - For an architecture diagram, the important boundary is that routers do not appear to own the logic; they delegate into services and persistence.

10. **Testing strategy**
   - `fastapi/tests/` includes smoke tests and domain tests for admin and collections behavior.
   - `conftest.py` implies shared fixtures for database/app setup.
   - The test layout mirrors the backend domains, which is useful evidence that the codebase is organized around feature boundaries rather than a single service layer.

11. **Frontend app structure**
   - The frontend is a Vite-based React app with TypeScript (`src/*.tsx`, `vite.config.ts`, `tsconfig*.json`).
   - UI is split into feature-oriented pages/components such as `Home`, `Bibliotheque` (library), `Recherche` (search), `RechercheUsers`, `AdminPanel`, and modal/detail components.
   - Styling is colocated per feature via CSS files like `Home.css`, `Bibliotheque.css`, and `AdminPanel.css`.

12. **Frontend data access and auth integration**
   - `src/api/collections.ts` is the clearest frontend API layer and likely encapsulates calls to backend collection endpoints.
   - `src/auth.tsx` suggests the frontend keeps authentication state or context separately from presentation components.
   - `App.tsx` and `main.tsx` are the app shell and bootstrap, while the page components consume API/auth helpers.

13. **End-to-end data flow**
   - A typical flow is: React page → frontend API helper/auth context → FastAPI router → service layer → models/database → response back through schemas to the UI.
   - For media search or metadata enrichment, the backend may additionally call the MangaDex integration before returning or storing results.

14. **Main architectural boundaries to draw**
   - Boundary 1: **Frontend vs backend**.
   - Boundary 2: **HTTP routing vs business logic** inside FastAPI.
   - Boundary 3: **Core app data vs external media provider** via the MangaDex adapter.
   - Boundary 4: **Public/user/admin/auth domains**, which are separated into their own routers and services.

Main entry points: [`fastapi/main.py`](https://github.com/karasu-huginn/3proj/blob/main/fastapi/main.py) (FastAPI app), [`react/src/App.tsx`](https://github.com/karasu-huginn/3proj/blob/main/react/src/App.tsx) (React app), [`fastapi/models.py`](https://github.com/karasu-huginn/3proj/blob/main/fastapi/models.py) (Models), [`fastapi/routers/collections.py`](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/collections.py) (Collections router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_react_app["React app<br/>frontend shell<br/>[App.tsx]"]
  node_react_main(("Bootstrap<br/>frontend entry<br/>[main.tsx]"))
  node_react_auth(("Auth state<br/>client auth<br/>[auth.tsx]"))
  node_react_api_collections["API client<br/>http client<br/>[collections.ts]"]
  node_react_home["Home<br/>page<br/>[Home.tsx]"]
  node_react_library["Library<br/>page<br/>[Bibliotheque.tsx]"]
  node_react_search["Search<br/>page<br/>[Recherche.tsx]"]
  node_react_user_search["User search<br/>page<br/>[RechercheUsers.tsx]"]
  node_react_admin["Admin panel<br/>page<br/>[AdminPanel.tsx]"]
  node_react_details["Details modal<br/>ui component"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api entry<br/>[main.py]"]
  node_backend_db[("Database<br/>persistence setup<br/>[database.py]")]
  node_backend_models["Models<br/>domain model<br/>[models.py]"]
  node_backend_schemas["Core schemas<br/>api schemas<br/>[schemas.py]"]
  node_backend_collections["Collections router<br/>feature router<br/>[collections.py]"]
  node_backend_users["Users router<br/>feature router<br/>[users.py]"]
  node_backend_admin["Admin router<br/>feature router<br/>[admin.py]"]
  node_backend_search["Search router<br/>feature router<br/>[search_router.py]"]
  node_backend_notifications["Notifications<br/>domain service<br/>[service.py]"]
  node_backend_social["Social service<br/>domain service<br/>[service.py]"]
end

subgraph group_backend_auth["Auth"]
  node_backend_auth_router["Auth router<br/>[router.py]"]
  node_backend_auth_service["Auth service<br/>auth logic<br/>[service.py]"]
  node_backend_auth_deps["Auth deps<br/>auth wiring<br/>[dependencies.py]"]
end

subgraph group_backend_media["Media"]
  node_backend_media_router["Media router<br/>feature router<br/>[router.py]"]
  node_backend_media_service["Media service<br/>domain service<br/>[service.py]"]
  node_backend_mangadex{{"MangaDex adapter<br/>external connector<br/>[mangadex.py]"}}
end

subgraph group_backend_tests["Tests"]
  node_backend_tests["Backend tests<br/>test suite<br/>[test_smoke.py]"]
end

node_react_main -->|"mounts"| node_react_app
node_react_app -->|"renders"| node_react_home
node_react_app -->|"renders"| node_react_library
node_react_app -->|"renders"| node_react_search
node_react_app -->|"renders"| node_react_user_search
node_react_app -->|"renders"| node_react_admin
node_react_library -->|"calls"| node_react_api_collections
node_react_app -->|"uses"| node_react_auth
node_react_library -->|"opens"| node_react_details
node_backend_main -->|"includes"| node_backend_collections
node_backend_main -->|"includes"| node_backend_users
node_backend_main -->|"includes"| node_backend_admin
node_backend_main -->|"includes"| node_backend_search
node_backend_main -->|"includes"| node_backend_auth_router
node_backend_main -->|"includes"| node_backend_media_router
node_backend_main -->|"configures"| node_backend_db
node_backend_collections -->|"reads/writes"| node_backend_models
node_backend_collections -->|"uses"| node_backend_schemas
node_backend_auth_router -->|"delegates"| node_backend_auth_service
node_backend_auth_router -->|"depends on"| node_backend_auth_deps
node_backend_auth_service -->|"reads/writes"| node_backend_models
node_backend_media_router -->|"delegates"| node_backend_media_service
node_backend_media_service -->|"calls"| node_backend_mangadex
node_backend_media_router -->|"uses"| node_backend_schemas
node_backend_notifications -->|"uses"| node_backend_models
node_backend_social -->|"uses"| node_backend_models
node_backend_search -->|"queries"| node_backend_models
node_backend_tests -->|"covers"| node_backend_collections
node_backend_tests -->|"covers"| node_backend_admin
node_backend_tests -->|"covers"| node_backend_models

click node_react_app "https://github.com/karasu-huginn/3proj/blob/main/react/src/App.tsx"
click node_react_main "https://github.com/karasu-huginn/3proj/blob/main/react/src/main.tsx"
click node_react_auth "https://github.com/karasu-huginn/3proj/blob/main/react/src/auth.tsx"
click node_react_api_collections "https://github.com/karasu-huginn/3proj/blob/main/react/src/api/collections.ts"
click node_react_home "https://github.com/karasu-huginn/3proj/blob/main/react/src/Home.tsx"
click node_react_library "https://github.com/karasu-huginn/3proj/blob/main/react/src/Bibliotheque.tsx"
click node_react_search "https://github.com/karasu-huginn/3proj/blob/main/react/src/Recherche.tsx"
click node_react_user_search "https://github.com/karasu-huginn/3proj/blob/main/react/src/RechercheUsers.tsx"
click node_react_admin "https://github.com/karasu-huginn/3proj/blob/main/react/src/AdminPanel.tsx"
click node_react_details "https://github.com/karasu-huginn/3proj/blob/main/react/src/MangaDetailModal.tsx"
click node_backend_main "https://github.com/karasu-huginn/3proj/blob/main/fastapi/main.py"
click node_backend_db "https://github.com/karasu-huginn/3proj/blob/main/fastapi/database.py"
click node_backend_models "https://github.com/karasu-huginn/3proj/blob/main/fastapi/models.py"
click node_backend_schemas "https://github.com/karasu-huginn/3proj/blob/main/fastapi/schemas.py"
click node_backend_collections "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/collections.py"
click node_backend_users "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/users.py"
click node_backend_admin "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/admin.py"
click node_backend_search "https://github.com/karasu-huginn/3proj/blob/main/fastapi/search_router.py"
click node_backend_auth_router "https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/router.py"
click node_backend_auth_service "https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/service.py"
click node_backend_auth_deps "https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/dependencies.py"
click node_backend_media_router "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/router.py"
click node_backend_media_service "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/service.py"
click node_backend_mangadex "https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/mangadex.py"
click node_backend_notifications "https://github.com/karasu-huginn/3proj/blob/main/fastapi/notifications/service.py"
click node_backend_social "https://github.com/karasu-huginn/3proj/blob/main/fastapi/social/service.py"
click node_backend_tests "https://github.com/karasu-huginn/3proj/blob/main/fastapi/tests/test_smoke.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_app,node_react_main,node_react_auth,node_react_api_collections,node_react_home,node_react_library,node_react_search,node_react_user_search,node_react_admin,node_react_details toneBlue
class node_backend_main,node_backend_db,node_backend_models,node_backend_schemas,node_backend_collections,node_backend_users,node_backend_admin,node_backend_search,node_backend_notifications,node_backend_social toneAmber
class node_backend_auth_router,node_backend_auth_service,node_backend_auth_deps toneMint
class node_backend_media_router,node_backend_media_service,node_backend_mangadex toneRose
class node_backend_tests toneIndigo
```

## Components

### Frontend

React + Vite UI and client-side state

- [React app](https://github.com/karasu-huginn/3proj/blob/main/react/src/App.tsx): frontend shell · Vite entry and app composition · `react/src/App.tsx`
- [Bootstrap](https://github.com/karasu-huginn/3proj/blob/main/react/src/main.tsx): frontend entry · Client app startup and mount point · `react/src/main.tsx`
- [Auth state](https://github.com/karasu-huginn/3proj/blob/main/react/src/auth.tsx): client auth · Frontend auth context/state · `react/src/auth.tsx`
- [API client](https://github.com/karasu-huginn/3proj/blob/main/react/src/api/collections.ts): http client · Frontend calls for collection operations · `react/src/api/collections.ts`
- [Home](https://github.com/karasu-huginn/3proj/blob/main/react/src/Home.tsx): page · Landing page UI · `react/src/Home.tsx`
- [Library](https://github.com/karasu-huginn/3proj/blob/main/react/src/Bibliotheque.tsx): page · Collection and library views · `react/src/Bibliotheque.tsx`
- [Search](https://github.com/karasu-huginn/3proj/blob/main/react/src/Recherche.tsx): page · Search UI and results · `react/src/Recherche.tsx`
- [User search](https://github.com/karasu-huginn/3proj/blob/main/react/src/RechercheUsers.tsx): page · User lookup and discovery UI · `react/src/RechercheUsers.tsx`
- [Admin panel](https://github.com/karasu-huginn/3proj/blob/main/react/src/AdminPanel.tsx): page · Privileged administration UI · `react/src/AdminPanel.tsx`
- [Details modal](https://github.com/karasu-huginn/3proj/blob/main/react/src/MangaDetailModal.tsx): ui component · Manga and list detail presentation · `react/src/MangaDetailModal.tsx`

### Backend

FastAPI application and domain services

- [FastAPI app](https://github.com/karasu-huginn/3proj/blob/main/fastapi/main.py): api entry · Backend composition and startup · `fastapi/main.py`
- [Database](https://github.com/karasu-huginn/3proj/blob/main/fastapi/database.py): persistence setup · Session and engine wiring · `fastapi/database.py`
- [Models](https://github.com/karasu-huginn/3proj/blob/main/fastapi/models.py): domain model · Persistent entities and ORM models · `fastapi/models.py`
- [Core schemas](https://github.com/karasu-huginn/3proj/blob/main/fastapi/schemas.py): api schemas · Shared request and response contracts · `fastapi/schemas.py`
- [Collections router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/collections.py): feature router · Collection CRUD and membership endpoints · `fastapi/routers/collections.py`
- [Users router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/users.py): feature router · User profile and account endpoints · `fastapi/routers/users.py`
- [Admin router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/admin.py): feature router · Privileged admin endpoints · `fastapi/routers/admin.py`
- [Search router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/search_router.py): feature router · Cross-domain search endpoints · `fastapi/search_router.py`
- [Notifications](https://github.com/karasu-huginn/3proj/blob/main/fastapi/notifications/service.py): domain service · Notification logic and payloads · `fastapi/notifications/service.py`
- [Social service](https://github.com/karasu-huginn/3proj/blob/main/fastapi/social/service.py): domain service · Social interaction logic · `fastapi/social/service.py`

### Auth

Authentication and session boundary

- [Auth router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/router.py): auth router · Login and session endpoints · `fastapi/auth/router.py`
- [Auth service](https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/service.py): auth logic · Authentication and token/session rules · `fastapi/auth/service.py`
- [Auth deps](https://github.com/karasu-huginn/3proj/blob/main/fastapi/auth/dependencies.py): auth wiring · FastAPI dependency integration · `fastapi/auth/dependencies.py`

### Media

Media search and external provider integration

- [Media router](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/router.py): feature router · Media search and metadata endpoints · `fastapi/routers/media/router.py`
- [Media service](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/service.py): domain service · Media orchestration and enrichment · `fastapi/routers/media/service.py`
- [MangaDex adapter](https://github.com/karasu-huginn/3proj/blob/main/fastapi/routers/media/mangadex.py): external connector · External media provider integration · `fastapi/routers/media/mangadex.py`

### Tests

Backend test suite

- [Backend tests](https://github.com/karasu-huginn/3proj/blob/main/fastapi/tests/test_smoke.py): test suite · Domain and smoke coverage · `fastapi/tests/test_smoke.py`

## Connections

- Bootstrap → React app: mounts · Bootstraps the React app
- React app → Home: renders · Composes major pages and views
- React app → Library: renders · Composes major pages and views
- React app → Search: renders · Composes major pages and views
- React app → User search: renders · Composes major pages and views
- React app → Admin panel: renders · Composes major pages and views
- Library → API client: calls · Uses API helper for backend requests
- React app → Auth state: uses · Shares auth state across the UI
- Library → Details modal: opens · Uses detail modal for item inspection
- FastAPI app → Collections router: includes · Registers feature routers
- FastAPI app → Users router: includes · Registers feature routers
- FastAPI app → Admin router: includes · Registers feature routers
- FastAPI app → Search router: includes · Registers feature routers
- FastAPI app → Auth router: includes · Registers auth routes
- FastAPI app → Media router: includes · Registers media routes
- FastAPI app → Database: configures · Initializes persistence layer
- Collections router → Models: reads/writes · Operates on persisted collection data
- Collections router → Core schemas: uses · Validates request/response payloads
- Auth router → Auth service: delegates · Routes auth flow into business logic
- Auth router → Auth deps: depends on · Uses dependency wiring for protection
- Auth service → Models: reads/writes · Manages auth-related state
- Media router → Media service: delegates · HTTP layer forwards into media logic
- Media service → MangaDex adapter: calls · Uses external provider adapter
- Media router → Core schemas: uses · Shares API payload contracts
- Notifications → Models: uses · Notification state is persisted with core data
- Social service → Models: uses · Social features relate to core entities
- Search router → Models: queries · Search spans multiple persisted domains
- Backend tests → Collections router: covers · Exercises collection behavior
- Backend tests → Admin router: covers · Exercises admin behavior
- Backend tests → Models: covers · Validates model layer behavior