final?

PROMPT.md

@@ -0,0 +1,81 @@
+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

README.md

@@ -17,7 +17,24 @@ This repo is a template to run a FastAPI server hosting a React+Tailwind app in
 
 Spaces are very well suited to vibe-code demos using Cursor, Lovable, Claude Code, etc. The hardest past is often to correctly configure the tooltip to make it work in the first place. This repo is intended to solve that.
 
-## Getting started
+## Main features
+
+- 🚀 Built for HF Spaces
+- ✨ Vibe-coding ready (see [PROMPT.md](./PROMPT.md))
+- 🤗 Support OAuth (Sign in with Hugging Face)
+- ⚡ FastAPI for the API²
+- 🎨 React + Tailwind for the UI
+- 💾 local SQLLite database + regular backups as HF dataset
+
+## Quick start
+
+1. Duplicate the Space.
+2. Set an `HF_TOKEN` as Space secret and `BACKUP_DATASET_ID` as Space variable. These will be used to make regular backups of the database.
+3. At this stage, Space should be running correctly on the Hub with a demo.
+4. For local development, follow the dev instructions below.
+5. Once server is running locally, you can start to edit it. All instructions are located in `PROMPT.md`. Inject that file in the vibe coding tool of your choice and start building!
+
+## Instructions
 
 The backend (Python + FastAPI) and the frontend (TS + React + Tailwind) are located respectively in the `backend/` and `frontend/` folder.
 

backend/Makefile

@@ -1,4 +1,4 @@
-.PHONY: quality style
+.PHONY: quality style dev preview test
 
 dev:
 	HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 uv run uvicorn src.app:app --reload

frontend/src/App.tsx

@@ -78,16 +78,18 @@ function App() {
 
           <div className="bg-gray-800/30 backdrop-blur-sm rounded-xl p-6 border border-gray-700/30">
             <div className="text-cyan-400 text-2xl mb-3">💾</div>
-            <h3 className="text-lg font-semibold mb-2">SQLite Database</h3>
+            <h3 className="text-lg font-semibold mb-2">
+              SQLite + Parquet backups
+            </h3>
             <p className="text-gray-300 text-sm">
-              (semi-)persistent data storage
+              Work with SQLite locally, but persist data in a HF dataset as parquet
             </p>
           </div>
         </div>
 
         <div className="bg-gray-800/20 backdrop-blur-sm rounded-xl p-6 border border-gray-700/20 mb-8">
           <h3 className="text-xl font-semibold mb-4 text-center">
-            Duplicate this Space, open the README, and make it yours.
+            Duplicate this Space to start building!
           </h3>
         </div>
       </div>

frontend/src/components/BackendHealthCheck.tsx

@@ -1,5 +1,5 @@
 import { useState, useEffect } from "react";
-import { BACKEND_URL, APP_CONFIG } from "../config/constants";
+import { BACKEND_URL, APP_CONFIG } from "../constants";
 
 interface BackendHealthCheckProps {
   checkInterval?: number;

frontend/src/components/OAuthButton.tsx

@@ -1,5 +1,5 @@
 import React, { useState, useEffect } from "react";
-import { BACKEND_URL } from "../config/constants";
+import { BACKEND_URL } from "../constants";
 import { apiFetch } from "../utils/apiFetch";
 
 interface UserInfo {

frontend/src/utils/apiFetch.ts

@@ -1,4 +1,4 @@
-import { BACKEND_URL } from "../config/constants";
+import { BACKEND_URL } from "../constants";
 
 export async function apiFetch(
   endpoint: string,