Closet AI

Your wardrobe, on your own computer, with an AI stylist on top.

Closet AI stores the clothes you own and builds outfits from them. Tell it where you are going — office, gym, a date — and it picks a complete outfit from your wardrobe using Google's Gemini model.

On Windows it runs as a single application file: nothing to install, nothing to compile, and no account on anybody else's server. Your clothes, photos and settings stay on your machine.

Download  →  Double-click  →  Use

---

Start here

I want to…	Go to
Use the app (no coding needed)	For everyone
Build it, run it, or work on the code	For developers
Understand how it is built	How it is put together
Package the Windows .exe	packaging/README.md

---

For everyone — use Closet AI

1. Download

1. Open the latest release.
2. In the Assets list, click ClosetAI-Windows-x64.exe.
3. Save it wherever you like — Desktop, Downloads, or a USB stick. It is one single file; there is nothing to unzip.

Direct download link:

https://github.com/Iyosiprograming/closet/releases/latest/download/ClosetAI-Windows-x64.exe

2. Run it

Double-click ClosetAI-Windows-x64.exe. That is the whole installation.

• Closet AI starts its own background server and opens the app in your default browser. There is no black terminal window and no window you need to keep open.
• The first start takes a few seconds.
• Open it again any time by double-clicking the same file (if it is already running, that just brings you back to it).

Windows may warn you the first time. The build is not code-signed yet, so SmartScreen can show "Windows protected your PC": click More info, then Run anyway. If absolutely nothing happens when you double-click, see Troubleshooting.

3. Set it up (about two minutes)

1. Create an account. Choose any username and password. This account exists only on your computer.
2. Add a Gemini API key. Settings → API configuration. Outfit suggestions are generated by Google's Gemini model, so it needs a key that belongs to you. Make one for free at https://aistudio.google.com/app/apikey and paste it in. It is stored on your computer and only used for your own requests.
3. Add your location (optional). Settings → Location, for example Addis Ababa. If you also add a free OpenWeather key, suggestions take today's weather into account.
4. Add a few clothes. Closet → + Add outfit. Each item gets a photo, a name, a colour, a type (top, bottom, shoes, …), a season and a formality.
5. Get an outfit. On the dashboard choose an occasion — Home, Office, Gym, Date, Party, Casual, Travel, or type your own — and press Get suggestion.

4. Where your data lives

Everything is in one folder on your computer:

%LOCALAPPDATA%\ClosetAI
├── data\closet.db      your wardrobe database (SQLite)
├── images\             the photos you uploaded
└── logs\               plain-text logs, handy when reporting a problem

Paste that path into the address bar of File Explorer to open it.

I want to…	Do this
Back up my wardrobe	Copy the whole %LOCALAPPDATA%\ClosetAI folder somewhere safe
Move to another PC	Copy that folder into the same place on the new PC
Update the app	Download the new .exe and delete the old one — your data stays
Start over from empty	Quit the app, delete the ClosetAI folder, start it again
Uninstall	Quit the app, then delete ClosetAI-Windows-x64.exe and the ClosetAI folder

5. Quitting the app

Closet AI keeps running in the background so the app stays reachable. To stop it: Settings → Application → Quit Closet AI. If the interface is not reachable any more, open Task Manager, find ClosetAI-Windows-x64.exe and choose End task.

Troubleshooting

What you see	What to do
Nothing happens when I double-click	Check Task Manager first — the app may already be running. Otherwise open %LOCALAPPDATA%\ClosetAI\logs\launcher.log: every startup problem is written there, including the reason.
No log file exists at all	Windows blocked the file. Click More info → Run anyway on the warning, or see the next row.
"Access is denied" and no window	Windows 11 Smart App Control is refusing the unsigned build. Turn it off under Windows Security → App & browser control → Smart App Control, or use a signed build — see packaging/README.md.
"We couldn't reach the server"	The page in your browser lost its backend — usually a tab left open from an earlier run. Just double-click ClosetAI.exe again; it opens the correct address itself.
Outfit suggestion fails	Open Settings → API configuration and check your Gemini key. An invalid or expired key is the usual cause.
A clothing card shows no photo	That image file is missing from %LOCALAPPDATA%\ClosetAI\images. Open the item and upload the photo again.
Something else	Please attach %LOCALAPPDATA%\ClosetAI\logs\launcher.log to your issue. It contains no passwords and no API keys.

---

For developers — build and run it

Requirements

Tool	Version	Needed for
uv	latest	backend dependencies and commands
Python	3.12+ (installed by uv)	backend
Node.js	20+	frontend
PowerShell	5.1+	building the Windows executable

End users need none of these — they only download the .exe.

Get the code

git clone https://github.com/Iyosiprograming/closet.git
cd closet

Run the backend

cd Backend
uv sync                # creates .venv and installs everything
uv run python main.py  # http://127.0.0.1:8000

Interactive API documentation is at http://127.0.0.1:8000/docs.

While developing, the backend keeps its data inside the repository: Backend/closet.db, Backend/images/, Backend/logs/ (all gitignored). It also serves a built frontend if Frontend/dist exists, so http://127.0.0.1:8000 can show the whole app on its own — handy for testing the packaged behaviour without packaging anything.

Useful commands, all from Backend/:

Command	What it does
uv run python main.py	Start the API on port 8000 with auto-reload
uv run uvicorn main:app --port 8000	Start it without auto-reload
uv run pytest	Run the test suite in Backend/Test/
uv sync	Install or update dependencies

Run the frontend

In a second terminal:

cd Frontend
npm install
npm run dev            # http://127.0.0.1:5173

The Vite dev server proxies /users, /clothes and /images to the backend, so the app and the API share one origin (the backend's auth cookies are SameSite=Lax, which browsers only send same-site).

Command	What it does
npm run dev	Dev server with hot reload
npm run build	Type-check, then build to dist/
npm run preview	Serve the production build locally
npm run typecheck	Type-check only

How the two halves talk

POST /users/login sets the access and refresh tokens as HTTP-only cookies, so JavaScript can never read them. Every protected backend route also declares the access token as a required ?token= query parameter, which no browser client could fill in on its own. The backend bridges the two: AccessTokenQueryMiddleware in Backend/main.py copies the cookie into ?token= when the parameter is missing, so the cookie stays the one source of truth.

Details, including the dev-server equivalent, are in Frontend/README.md.

Build the Windows executable

./build_windows.ps1

This builds the frontend, installs the backend dependencies (PyInstaller comes from the dev dependency group) and produces:

release/ClosetAI-Windows-x64.exe

That single file bundles the Python interpreter, the FastAPI backend and the production frontend. packaging/README.md covers what is inside it, where user data is stored, how to test it, how to publish a GitHub release and how to troubleshoot startup failures.

Project structure

closet/
├── Backend/
│   ├── main.py                 FastAPI app: routes, middleware, static frontend
│   ├── app/
│   │   ├── Auth/               password hashing (argon2), JWT creation/verification
│   │   ├── Core/               paths, logging, database session, lifecycle
│   │   ├── Helper/             Gemini and OpenWeather integrations
│   │   ├── Models/             SQLAlchemy models (User, Clothe)
│   │   ├── Routers/            /users and /clothes endpoints
│   │   ├── Schemas/            Pydantic request/response schemas
│   │   └── Services/           business logic
│   └── pyproject.toml          dependencies (uv), including the packaging tools
├── Frontend/
│   ├── src/
│   │   ├── components/         Navbar, ClothingCard, modals, toasts, occasion picker
│   │   ├── pages/              Login, Dashboard, Closet, Settings
│   │   ├── services/api.ts     every fetch call to the backend
│   │   ├── types/api.ts        types mirroring the backend schemas
│   │   └── utils/              session clock, friendly labels
│   └── vite.config.ts          dev server + API proxy
├── packaging/
│   ├── launcher.py             desktop entry point: starts the API, opens the app
│   ├── ClosetAI.spec           PyInstaller build definition
│   └── README.md               build, release, data paths, troubleshooting
└── build_windows.ps1           one-command Windows build

API reference

Method	Path	Purpose
POST	/users/	Register a user
POST	/users/login	Log in (sets the auth cookies)
POST	/users/refresh	Renew the access token
POST	/users/logout	Clear the auth cookies
PATCH	/users/location	Save the city used for weather
PATCH	/users/api-keys	Save the Gemini / OpenWeather keys
GET	/clothes/	List the user's clothes
POST	/clothes/	Add a clothing item (multipart form)
GET	/clothes/{clothe_id}	One clothing item
PATCH	/clothes/{clothe_id}	Update an item (multipart form)
DELETE	/clothes/{clothe_id}	Delete an item
GET	/clothes/ai-suggestion?occasion=…	AI outfit for an occasion
GET	/health	Readiness probe and app status
POST	/app/shutdown	Quit the desktop app (launcher runs only)

Tech stack

Layer	Stack
Backend	Python 3.12, FastAPI, SQLAlchemy 2, SQLite, PyJWT, pwdlib + argon2, uvicorn
AI / integrations	google-genai (Gemini 2.5 Flash), OpenWeather (optional)
Frontend	React 19, TypeScript, Vite, Tailwind CSS 4, React Router, lucide-react
Desktop build	PyInstaller (one file, no console window), PowerShell build script

Security notes

• Access and refresh tokens live in HTTP-only cookies. Nothing is written to localStorage, sessionStorage, a URL or the browser console.
• API keys are sent only to the local backend, stored in the local SQLite database, and cleared from the form after saving.
• The packaged app listens on 127.0.0.1 only, on a port Windows picks for it, and never exposes the API to the network.
• Known gaps before any hosted deployment: Backend/app/Auth/jwt.py still uses a placeholder SECRET_KEY constant, and CORS is a wide-open allow_origins=["*"] kept for the dev server. Both should be configuration-driven for a server deployment. The released executable is unsigned, which is why Windows warns about it on first run.

Contributing

Small, readable files are the house style — please keep changes easy for a mid-level developer to follow, and avoid new dependencies unless they solve a real problem.

cd Frontend && npm run typecheck    # frontend types
cd Backend  && uv run pytest        # backend tests

Then open a pull request against main.

Docs and media

• packaging/README.md — building, releasing, user data paths, troubleshooting
• Frontend/README.md — auth details, endpoints, structure
• Screenshots and recordings for this README belong in docs/media/. Search this file for TODO(media) to find every place one is expected.

Roadmap

Done:

• Username and password authentication with refresh tokens
• Full wardrobe CRUD with image upload
• AI outfit suggestions from the whole wardrobe (Gemini)
• Weather-aware suggestions (optional OpenWeather key)
• Single-file Windows application for non-technical users

---

How it is put together

┌───────────────────────── ClosetAI.exe ─────────────────────────┐
│                                                                │
│   launcher  ──starts──▶  uvicorn + FastAPI   ──serves──▶  React │
│   (packaging)              (Backend/)          (Frontend/dist)  │
│        │                        │                              │
│        │                        ├── SQLite  %LOCALAPPDATA%\…\data
│        │                        └── images  %LOCALAPPDATA%\…\images
│        └──opens the app in the default browser                  │
└────────────────────────────────────────────────────────────────┘

The launcher picks a free localhost port, starts the backend on it, waits for /health to answer, opens the app, and shuts the backend down when you quit. The plain-English version of everything in this diagram is in packaging/README.md.

---

Project goal

Closet AI started as a backend exercise — FastAPI, SQLAlchemy, SQLite, REST design, dependency injection, JWT authentication and Gemini integration. It grew into a complete application: a React frontend, and a desktop build that a non-technical person can download and use without installing anything.

Screenshots