| This repository contains a full-stack application designed to be deployed in a Hugging Face Space. | |
| ## backend/ | |
| The backend/ folder contains the API server, implemented in Python using FastAPI. Project is built using uv. | |
| Main commands in that folder are: | |
| - `make dev` to run a local dev server | |
| - `make style` to apply code formatting | |
| - `make quality` to check code format | |
| - `make test` to run tests | |
| - `uv add ...` to add a new dependency | |
| When working in the `backend/` folder, please keep these instructions in mind: | |
| - API is defined in `backend/src/app.py` using FastAPI. For now it contains an health check endpoint and endpoints to deal with the counter. | |
| - You can define as many new endpoints as you need. Follow the FastAPI best practices. All routes should be defined under `/api` prefix. | |
| - OAuth is already baked in. If an endpoint requires the user to be authenticated, pass `oauth_info: RequiredOAuth` as argument. If authentication is optional, pass `oauth_info: OptionalOAuth`. If you don't need authentication, no need for that arg. `RequiredOAuth` is a dataclass of type `OAuthInfo` (see below). `OptionalOAuth` is of type `OAuthInfo | None`. | |
| - schemas are defined in `backend/src/schemas.py`. We use [SQLModel](https://sqlmodel.tiangolo.com/) to define them which is a wrapper on top of Pydantic and SQLAlchemy. Any object defined in this module with `table=True` will result in a table in the database. Since all models are Pydantic object, you can use them seamlessly with FastAPI. See examples in `backend/src/app.py` on how to load an object from database and how to insert one. | |
| - The FastAPI server and Database are configured in `backend/src/app_factory.py`. DO NOT UPDATE this file. | |
| - If the `BACKUP_DATASET_ID` and `HF_TOKEN` env variables are defined, the database will be regularly exported as parquet files in a dataset on the Hub. This is useful to have persistent storage in a Space. Export is done once every 5 minutes in an optimized way (only new data is upload). All of the logic is defined in `backend/src/app_factory.py` and `backend/src/parquet.py`. DO NOT UPDATE these files. | |
| - App config and constants are defined in `backend/src/constants.py`. You can add new config value if required. Do not update existing ones unless explicitly requested. | |
| ### OAuthInfo definition | |
| Here is how `OAuthInfo` dataclass is defined in Python. Useful when a user is authenticated. | |
| ```py | |
| @dataclass | |
| class OAuthUserInfo: | |
| sub: str | |
| name: str | |
| preferred_username: str | |
| email_verified: Optional[bool] | |
| email: Optional[str] | |
| picture: str | |
| profile: str | |
| website: Optional[str] | |
| is_pro: bool | |
| can_pay: Optional[bool] | |
| orgs: Optional[List[OAuthOrgInfo]] | |
| @dataclass | |
| class OAuthInfo: | |
| access_token: str | |
| access_token_expires_at: datetime.datetime | |
| user_info: OAuthUserInfo | |
| state: Optional[str] | |
| scope: str | |
| ``` | |
| ## frontend/ | |
| The frontend/ folder contains the UI implemented in TS with React and Tailwind. Project is built using vite. | |
| Main commands in that folder are: | |
| - `pnpm install` to install packages | |
| - `pnpm dev` to run a local dev environment | |
| - `pnpm style` to apply code formatting | |
| - `pnpm quality` to check code format | |
| - `pnpm add (-D) ...` to add a new package | |
| When working in the `frontend/` folder, please keep these instructions in mind: | |
| - UI is a single-page application. It doesn't use any router. You must keep this structure. | |
| - Main app is located in `frontend/src/App.tsx`. | |
| - Components are defined in `frontend/src/components`. | |
| - To make request to the backend, use `apiFetch` from `frontend/src/utils/apiFetch.ts`. It is a wrapper around `fetch` with a predefined backend url and authenticated calls. | |
| - Authentication has to be done using the `OAuthButton` defined in `frontend/src/components/OAuthButton.tsx`. DO NOT UPDATE this file. | |
| - The `BackendHealthCheck` component in `frontend/src/components/BackendHealthCheck.tsx` is made for dev purpose only. DO NOT UPDATE this file except if requested specifically. | |
| - The `Counter` component in `frontend/src/components/Counter.tsx` is a good example on how to define a component making calls to the backend. You can remove / update it if necessary. | |
| - You can define as many new components as you want. Make each component self contained. Define new components in `frontend/src/components/`. | |
| - App config and constants are defined in `frontend/src/constants.ts` (backend url, health check interval, etc.). You can add new config value if required. | |
| - Assets (images, etc.) should be added to the `frontend/src/assets` folder. There is a `frontend/src/assets/huggingface.svg` in it (Hugging Face logo). DO NOT REMOVE it. You can reuse it if you want and/or add any assets you want. | |
| - Config files (`frontend/vite.config.ts`, `frontend/tsconfig.json`, `frontend/tsconfig.node.json`, `frontend/eslint.config.js`, `frontend/src/vite-env.d.ts`) should not be updated expect if explicitly requested by user. | |
| - DO NOT MODIFY `frontend/src/index.css` (which imports tailwind) and `frontend/src/main.tsx` (main imports). | |
| ## How to add a new feature? | |
| - add new API routes in `backend/src/app.py`. If needed, add a new schema in `backend/src/schemas.py`. Use authentication if required. | |
| - add a new component in `frontend/src/components` and update `frontend/src/App.tsx` to include it. | |
| - let the user run `cd frontend && pnpm dev` and `cd backend && make dev` in 2 terminals to try it out | |
| - once tested, commit the changes and push to remote branch |