karasu-huginn/3proj

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.