131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# Canteen Asset Tracker — Project Structure
|
|
|
|
Two projects, one API contract.
|
|
|
|
## Repositories
|
|
|
|
```
|
|
~/projects/canteen-asset-tracker/ ← Web app (Python/FastAPI backend + SPA frontend)
|
|
~/projects/canteen-asset-tracker-android/ ← Android app (Kotlin, Jetpack Compose)
|
|
```
|
|
|
|
## Web App (`canteen-asset-tracker`)
|
|
|
|
```
|
|
canteen-asset-tracker/
|
|
├── server.py FastAPI backend — all 78 API routes + DB logic
|
|
├── openapi.yaml **Shared API contract** — source of truth for both projects
|
|
├── assets.db SQLite database (WAL mode, foreign keys on)
|
|
├── static/
|
|
│ └── index.html Single-page frontend (276 KB, self-contained)
|
|
├── tests/ pytest test suite (319 tests)
|
|
├── uploads/ User-uploaded photos/icons
|
|
├── cert.pem / key.pem Self-signed TLS certs
|
|
├── requirements.txt Python deps (fastapi, uvicorn, pytesseract, pillow)
|
|
├── start.sh Launch script (production)
|
|
└── smoke_test.sh Smoke test suite
|
|
```
|
|
|
|
- **Port:** 8901 (HTTPS)
|
|
- **URL:** https://canteen.ourpad.casa:8901
|
|
- **Frontend:** Single HTML file — no build step, no npm. All JS/CSS/HTML in one file.
|
|
- **Backend:** FastAPI with SQLite (WAL mode). 48 named routes + 30 dynamic settings routes.
|
|
- **Tests:** 319 backend tests passing. No frontend tests yet.
|
|
|
|
## Android App (`canteen-asset-tracker-android`)
|
|
|
|
```
|
|
canteen-asset-tracker-android/
|
|
├── app/
|
|
│ ├── src/main/java/com/canteen/assettracker/
|
|
│ │ ├── network/
|
|
│ │ │ └── RetrofitModule.kt API client config (points to web app URL)
|
|
│ │ ├── ui/
|
|
│ │ │ ├── login/ Login screen + ViewModel
|
|
│ │ │ ├── dashboard/ Dashboard screen + ViewModel
|
|
│ │ │ └── settings/ Settings screen + ViewModel
|
|
│ │ └── location/
|
|
│ │ └── ProximityEngine.kt GPS proximity logic
|
|
│ └── build/ Build outputs (APK, test reports)
|
|
├── build.gradle.kts Root build config
|
|
├── settings.gradle.kts
|
|
├── gradlew / gradlew.bat Gradle wrapper
|
|
└── keystore.properties Signing keys
|
|
```
|
|
|
|
- **Package:** `com.canteen.assettracker`
|
|
- **API Base URL:** `https://canteen.ourpad.casa:8901/` (hardcoded in `RetrofitModule.kt`)
|
|
- **Tests:** 3 ViewModel/engine test classes, all passing (debug + release)
|
|
- **Built APK:** run `./gradlew assembleRelease`
|
|
|
|
## API Contract
|
|
|
|
`openapi.yaml` is the **single source of truth**. When you change the backend:
|
|
|
|
1. Update `server.py`
|
|
2. Update `openapi.yaml` to match
|
|
3. Android team (or future-you) can see exactly what changed
|
|
|
|
The spec covers:
|
|
- **48 named routes** across assets, check-ins, customers, locations, rooms, users, auth, geofences, visits, activity, stats, exports, uploads, and OCR
|
|
- **30 dynamic settings routes** (`/api/settings/{entity}` for 6 entity types)
|
|
- All request/response schemas
|
|
- Query parameters and path parameters
|
|
|
|
### Quick reference — main route groups
|
|
|
|
| Group | Routes |
|
|
|------------|-------------------------------|
|
|
| Auth | login, me |
|
|
| Assets | CRUD + search by machine ID |
|
|
| Check-ins | CRUD (GPS + photo + notes) |
|
|
| Customers | CRUD with contacts |
|
|
| Locations | CRUD + child rooms |
|
|
| Rooms | CRUD (nested under locations) |
|
|
| Users | CRUD |
|
|
| Geofences | CRUD + user assignment (service areas) |
|
|
| Visits | CRUD + stats |
|
|
| Stats | Dashboard aggregates |
|
|
| Exports | Assets CSV, Check-ins CSV, Service Summary CSV |
|
|
| Uploads | Icon + Photo upload |
|
|
| OCR | Extract machine ID from sticker image |
|
|
| Settings | Dynamic CRUD for 6 entity types |
|
|
| Proximity | Find assets near GPS point |
|
|
| Activity | Activity feed |
|
|
|
|
## Working with both projects
|
|
|
|
### Adding a feature to BOTH web + Android
|
|
1. Design the endpoint in `openapi.yaml` first
|
|
2. Implement in `server.py`
|
|
3. Run backend tests
|
|
4. Implement Android client code + run Android tests
|
|
|
|
### Adding a feature to web ONLY
|
|
1. Add endpoint to `server.py`
|
|
2. Update `openapi.yaml`
|
|
3. Android app ignores the new endpoint — no changes needed
|
|
|
|
### Adding a feature to Android ONLY
|
|
1. Plan the endpoint in `openapi.yaml` (even if backend isn't ready)
|
|
2. Build Android client against the planned contract
|
|
3. Backend implements later
|
|
|
|
## Running
|
|
|
|
```bash
|
|
# Web app
|
|
cd ~/projects/canteen-asset-tracker
|
|
./start.sh # production
|
|
# or: uvicorn server:app --reload # development
|
|
|
|
# Tests
|
|
cd ~/projects/canteen-asset-tracker
|
|
python -m pytest tests/ -v
|
|
|
|
# Android
|
|
cd ~/projects/canteen-asset-tracker-android
|
|
./gradlew assembleRelease # build APK
|
|
./gradlew test # run unit tests
|
|
```
|