sagnik/Project_Velocity
2
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Built the native SwiftUI app shell mirroring the WebOS interface (Dashboard, Inventory, Oracle tabs) (#2)

Browse Source 
I have attached the screenshots of the native SwiftUI app.

<img width="1705" alt="image.png" src="attachments/59fec2f3-0ae2-4b58-9349-457618ea0678">
<img width="1699" alt="image.png" src="attachments/0bf7c4f9-c883-4929-be36-774685b82fc4">
<img width="1698" alt="image.png" src="attachments/e3407e84-aaf2-45c0-9325-247d4020bace">
<img width="1694" alt="image.png" src="attachments/ee2cd47d-800d-4a40-855c-d54856680e79">
<img width="1694" alt="image.png" src="attachments/a2c902f1-9bc9-4427-8cae-b5801527c1ff">

Co-authored-by: Sayan Datta <sayan@Sayans-MacBook-Air.local>
Reviewed-on: #2
Co-authored-by: sayan <sayan@desineuron.in>
Co-committed-by: sayan <sayan@desineuron.in>
This commit was merged in pull request #2.
This commit is contained in:
sayan
2026-03-07 18:46:02 +05:30
committed by sagnik
parent 8fe2344e71
commit cb6c752c8e
33 changed files with 6930 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

457
.Agent Context/gitea_contribution_guide.md Normal file
View File

@@ -0,0 +1,457 @@
# Project Velocity — Gitea Feature Contribution Guide
**Version:** 1.1
**Last Updated:** 2026-03-07
**Upstream Repository (Sagnik's):** `https://git.desineuron.in/sagnik/Project_Velocity`
**Your Fork:** `https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity`
> This document is the **canonical guide** for every team member contributing to Project Velocity.
> The team uses a **Fork-based workflow**: each contributor has their own fork of Sagnik's repository. All features are developed in your fork and merged into the upstream via Pull Requests.
> It covers the full lifecycle: Issue → Branch → Commit → Push → Pull Request — both via the **CLI** and via **Antigravity Source Control UI**.
### How the Fork Model Works
```text
[upstream] sagnik/Project_Velocity ← the source of truth
↑ Pull Requests
[your fork] <you>/Project_Velocity ← where you develop
↑ git push
[local] /your/machine/Project_Velocity
```
- `upstream` = Sagnik's repo — you **pull** from here to stay in sync.
- `origin` = Your fork — you **push** your branches here.
- PRs go **from your fork → upstream**.
---
## Table of Contents
1. [Naming Conventions](#naming-conventions)
2. [One-Time Setup — Fork & Remotes](#one-time-setup--fork--remotes)
3. [Step 0 — Pre-flight: Populate `.gitignore` & `.gitkeep`](#step-0--pre-flight)
4. [Step 1 — Create a Gitea Issue](#step-1--create-a-gitea-issue)
5. [Step 2 — Sync with Upstream Before Branching](#step-2--sync-with-upstream-before-branching)
6. [Step 3 — Create a Feature Branch](#step-3--create-a-feature-branch)
7. [Step 4 — Make Your Changes & Commit](#step-4--make-your-changes--commit)
8. [Step 5 — Push the Branch to Your Fork](#step-5--push-the-branch-to-your-fork)
9. [Step 6 — Create a Pull Request (Fork → Upstream)](#step-6--create-a-pull-request-fork--upstream)
10. [Quick Reference — CLI Cheat Sheet](#quick-reference--cli-cheat-sheet)
---
## Naming Conventions
Consistent naming keeps the repository clean and makes history easy to read.
| Type | Format | Example |
|------|--------|---------|
| **Issue Title** | `feat : <Short description>` | `feat : Build the native SwiftUI app shell` |
| **Branch Name** | `feat/#<issue-number>` | `feat/#12` |
| **Commit Message** | `feat(scope): <what changed>` or `fix(scope): <what was fixed>` | `feat(ios): add Dashboard, Oracle and Sentinel tab views` |
> Use `fix`, `chore`, `docs`, `refactor`, or `test` instead of `feat` where appropriate.
---
## One-Time Setup — Fork & Remotes
Do this **once** when you first clone your fork onto a new machine. You only need to do this once per machine.
### 1. Clone your fork
```bash
git clone https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git
cd Project_Velocity
```
### 2. Add the upstream remote (Sagnik's repo)
```bash
git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git
```
### 3. Verify your remotes
```bash
git remote -v
```
You should see **two** remotes:
```text
origin https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git (fetch)
origin https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git (push)
upstream https://git.desineuron.in/sagnik/Project_Velocity.git (fetch)
upstream https://git.desineuron.in/sagnik/Project_Velocity.git (push)
```
> ⚠️ If you only see `origin`, you haven't added `upstream` yet. Run step 2 above.
### Via Antigravity Source Control UI
Antigravity does not have a direct UI button to add a new remote. Do this once via the terminal:
1. Open a terminal inside Antigravity (`Ctrl + `` ` `` ` `).
2. Run: `git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git`
3. The upstream remote will now appear in the **Graph** section of Source Control.
---
## Step 0 — Pre-flight
Before pushing anything, ensure these files are properly configured at the **root of the repository**.
### `.gitignore`
A root `.gitignore` already exists at the repository root. It covers:
- **macOS** system files (`DS_Store`, etc.)
- **Node / Vite / React** (`app/node_modules/`, `app/dist/`)
- **Xcode / Swift** (derived data, `.xcuserdata`, build artifacts)
- **Python / ComfyUI** (`__pycache__`, `.venv`, model weights)
- **Infrastructure** (Terraform state, secrets)
**You should never commit:**
- API keys or secrets (`.env` files are ignored)
- `node_modules/` directory
- Xcode `DerivedData/` or `.xcuserdata/`
- Python virtual environments (`.venv/`, `venv/`)
### `.gitkeep`
A `.gitkeep` file is used to **track an otherwise empty directory** in Git (Git does not track empty folders).
**When to add one:** If you create a new directory that should be committed but has no files yet, add an empty `.gitkeep` file inside it:
```bash
touch path/to/your/new-empty-folder/.gitkeep
```
---
## Step 1 — Create a Gitea Issue
Every feature or bug fix must start with a **Gitea Issue**. Issues must be created in **Sagnik's upstream repository** — not your fork. The upstream is the source of truth for the project, and `Closes #<N>` in your PR description will only auto-close the issue if it lives in the same repo your PR targets.
### Via Browser (Gitea Web UI)
1. Go to **Sagnik's upstream repo**: `https://git.desineuron.in/sagnik/Project_Velocity`.
2. Click on the **Issues** tab.
3. Click the green **New Issue** button.
4. Fill in the title using the format:
```
feat : <Short description of your feature>
```
**Example:**
```
feat : Build the native SwiftUI app shell mirroring the WebOS interface
```
5. Add a description explaining:
- **What** you are building.
- **Why** it is needed.
- **Acceptance criteria** (what "done" looks like).
6. Assign the issue to yourself.
7. Click **Submit**. Note down the **Issue Number** (e.g., `#12`) — you will need it for the branch name.
### Via CLI (using `curl` or Gitea API)
```bash
# Replace placeholders before running
GITEA_URL="https://git.desineuron.in"
GITEA_TOKEN="<YOUR_PERSONAL_ACCESS_TOKEN>" # Generate at: Profile → Settings → Applications
REPO_OWNER="sagnik" # Issues go in the UPSTREAM repo
REPO_NAME="Project_Velocity"
ISSUE_TITLE="feat : <Short description of your feature>"
ISSUE_BODY="<Detailed description of what you are building and why>"
curl -s -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues" \
-H "Content-Type: application/json" \
-H "Authorization: token $GITEA_TOKEN" \
-d "{
\"title\": \"$ISSUE_TITLE\",
\"body\": \"$ISSUE_BODY\",
\"assignees\": [\"$REPO_OWNER\"]
}"
```
> The response JSON will contain the `number` field — **this is your issue number**.
---
## Step 2 — Sync with Upstream Before Branching
Before creating a feature branch, **always** pull the latest changes from **`upstream`** (Sagnik's repo) — not from your fork (`origin`). This ensures your work starts from the most up-to-date version of the project.
### Via CLI
```bash
# Navigate to your project root
cd "/path/to/Project_Velocity"
# Switch to main
git checkout main
# Fetch all branches from upstream
git fetch upstream
# Merge upstream/main into your local main
git merge upstream/main
# (Optional) Push the synced main to your own fork to keep it up to date
git push origin main
```
> **Why `upstream` and not `origin`?**
> `origin` is your personal fork — it only knows about changes you've pushed.
> `upstream` is Sagnik's repository — the actual source of truth for the project.
### Via Antigravity Source Control UI
Antigravity's sync button pulls from `origin` by default. To sync from upstream, use the terminal:
1. Open a terminal in Antigravity (`Ctrl + `` ` `` ` `).
2. Run:
```bash
git fetch upstream && git merge upstream/main
```
3. Then click the **↺ (Refresh)** icon in the Source Control panel to refresh the view.
4. Confirm the **Graph** section shows your local `main` is aligned with `upstream/main`.
---
## Step 3 — Create a Feature Branch
Branch name format: **`feat/#<ISSUE_NUMBER>`**
**IMPORTANT:** Replace `<ISSUE_NUMBER>` with the actual number from Step 1.
### Via CLI
```bash
# Make sure you are on main first
git checkout main
# Create and switch to the new branch
git checkout -b feat/#<ISSUE_NUMBER>
# Example:
# git checkout -b feat/#12
```
### Via Antigravity Source Control UI
1. In the **Source Control** panel, look at the bottom **Graph** section.
2. Click on the **branch name** shown next to the current `HEAD` commit (e.g., `main`).
3. A branch picker will appear at the top of the screen.
4. Type the new branch name exactly: `feat/#<ISSUE_NUMBER>`
5. Select **"Create new branch: feat/#<ISSUE_NUMBER>"** from the dropdown.
6. Confirm. Your working branch is now set to the new feature branch.
---
## Step 4 — Make Your Changes & Commit
### Stage Your Files
#### Via CLI
```bash
# Stage specific files
git add path/to/changed/file.swift
# Stage all changed/new files at once (use with care)
git add .
# Review what is staged before committing
git status
```
#### Via Antigravity Source Control UI
1. In the **Source Control** panel, you will see two sections:
- **Staged Changes** — files ready to be committed.
- **Changes** — files that are modified but not yet staged.
2. To **stage a file**: Hover over it in the **Changes** section and click the **`+`** (plus) icon that appears on the right.
3. To **unstage a file**: Hover over it in **Staged Changes** and click the **`-`** (minus) icon.
4. To **stage all changes at once**: Click the **`+`** (plus) icon next to the **Changes** section header.
### Write Your Commit Message
Use the **Conventional Commits** format:
```
<type>(scope): <short summary>
```
| Type | When to Use |
|------|-------------|
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation changes only |
| `refactor` | Code restructured, no behavior change |
| `chore` | Config, build scripts, dependencies |
| `test` | Adding or fixing tests |
**Example commit messages:**
```
feat(ios): add Dashboard, Oracle, Sentinel, and Inventory tab views
feat(ios): implement AppStore with lead, visitor, and metrics models
fix(ios): correct ARSunOverlayView coordinate calculations
docs(agent): add velocity_ios_bible.md technical reference
```
### Commit
#### Via CLI
```bash
git commit -m "<type>(scope): <short summary of your change>"
# Example:
# git commit -m "feat(ios): add Dashboard, Oracle, Sentinel tab views mirroring WebOS"
```
#### Via Antigravity Source Control UI
1. Ensure your files are in the **Staged Changes** section.
2. Click the **Message** text field at the top of the Source Control panel (placeholder: `Message (⌘Enter to com...)`).
3. Type your commit message following the Conventional Commits format above.
4. *(Optional)* Click **Generate ✦** to let Antigravity AI suggest a commit message based on your staged diffs — review it before accepting.
5. Click the blue **✓ Commit** button (or press `⌘ + Enter`) to commit.
---
## Step 5 — Push the Branch to Gitea
### Via CLI
```bash
# Push your feature branch to the remote (origin)
git push origin feat/#<ISSUE_NUMBER>
# Example:
# git push origin feat/#12
```
If this is the **first push** of a new branch, Git may ask you to set the upstream:
```bash
git push --set-upstream origin feat/#<ISSUE_NUMBER>
```
### Via Antigravity Source Control UI
1. After committing, look at the **Changes** header in the Source Control panel.
2. Click the **`...` (More Actions)** menu (top-right of the Changes section header).
3. Select **Push** from the dropdown.
4. Alternatively, click the **↑ (Publish/Push)** cloud icon if visible next to the branch name in the status bar or Graph section.
5. Antigravity will push your local feature branch to `origin/feat/#<ISSUE_NUMBER>` on Gitea.
---
## Step 6 — Create a Pull Request (Fork → Upstream)
Since you are working on a fork, your PR goes **from your fork's feature branch → Sagnik's upstream `main`**. This is a cross-repository PR.
### Via Browser (Gitea Web UI)
1. Go to **Sagnik's upstream repo**: `https://git.desineuron.in/sagnik/Project_Velocity`.
2. Click the **Pull Requests** tab → **New Pull Request**.
3. Click **"compare across forks"** (Gitea shows this option when creating a cross-fork PR).
4. Set up the PR direction:
- **Base repository:** `sagnik/Project_Velocity` — **Base branch:** `main`
- **Head repository:** `<YOUR_USERNAME>/Project_Velocity` — **Compare branch:** `feat/#<ISSUE_NUMBER>`
5. Fill in the PR form:
- **Title:** `feat(scope): <Short description>`
- **Description:**
```
## Summary
<What does this PR do?>
## Changes
- <List the main changes>
## Related Issue
Closes #<ISSUE_NUMBER>
```
6. Assign **Sagnik** as reviewer.
7. Click **Create Pull Request**.
> 💡 **Alternatively**, after you push your branch to your fork (`origin`), Gitea may show a yellow banner inside Sagnik's upstream repo prompting you to create a cross-fork PR automatically. Click that if it appears.
### Via CLI (using Gitea API)
For a cross-fork PR, the `head` must include your fork username as a prefix.
```bash
GITEA_URL="https://git.desineuron.in"
GITEA_TOKEN="<YOUR_PERSONAL_ACCESS_TOKEN>"
UPSTREAM_OWNER="sagnik" # Sagnik's username
UPSTREAM_REPO="Project_Velocity"
YOUR_USERNAME="<YOUR_USERNAME>" # Your Gitea username
FEATURE_BRANCH="feat/#<ISSUE_NUMBER>"
PR_TITLE="feat(scope): <Short description>"
PR_BODY="## Summary\n<What does this PR do?>\n\n## Changes\n- <List main changes>\n\n## Related Issue\nCloses #<ISSUE_NUMBER>"
curl -s -X POST "$GITEA_URL/api/v1/repos/$UPSTREAM_OWNER/$UPSTREAM_REPO/pulls" \
-H "Content-Type: application/json" \
-H "Authorization: token $GITEA_TOKEN" \
-d "{
\"title\": \"$PR_TITLE\",
\"body\": \"$PR_BODY\",
\"head\": \"$YOUR_USERNAME:$FEATURE_BRANCH\",
\"base\": \"main\"
}"
```
> Note the `head` format: `"<YOUR_USERNAME>:feat/#<ISSUE_NUMBER>"` — this tells Gitea the branch lives in your fork, not the upstream.
---
## Quick Reference — CLI Cheat Sheet
Copy and fill in the placeholders (`<...>`) before running.
```bash
# ── ONE-TIME SETUP (do this once per machine) ─────────────────
cd "/path/to/Project_Velocity"
git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git
git remote -v # verify: you should see both origin and upstream
# ── 1. Create the Gitea Issue ──────────────────────────────────
# Go to Gitea web UI or use the curl command in Step 1
# Title format: feat : <Short description>
# Note the issue number: <ISSUE_NUMBER>
# ── 2. Sync from upstream main ────────────────────────────────
git checkout main
git fetch upstream
git merge upstream/main
git push origin main # keep your fork in sync too
# ── 3. Create & switch to feature branch ─────────────────────
git checkout -b feat/#<ISSUE_NUMBER>
# ── 4. Stage & Commit ─────────────────────────────────────────
git add .
git status # double-check what is staged
git commit -m "<type>(scope): <short summary>"
# ── 5. Push branch to YOUR FORK (origin) ──────────────────────
git push origin feat/#<ISSUE_NUMBER>
# ── 6. Create Pull Request (fork → upstream) ──────────────────
# Go to: https://git.desineuron.in/sagnik/Project_Velocity
# Pull Requests → New Pull Request → Compare across forks
# head: <YOUR_USERNAME>/Project_Velocity : feat/#<ISSUE_NUMBER>
# base: sagnik/Project_Velocity : main
```
---
## Tips & Best Practices
- **One issue = one branch = one PR.** Keep your changes focused.
- **Always sync from `upstream`, not `origin`.** Your fork doesn't automatically know about changes Sagnik pushes. Run `git fetch upstream && git merge upstream/main` regularly.
- **Commit often, push when ready.** Small commits make code review easier.
- **Never commit directly to `main`.** Always work on a feature branch.
- **Push to `origin`, PR to `upstream`.** Push goes to your fork. The PR targets Sagnik's repo.
- **Reference issues in PRs.** Using `Closes #<ISSUE_NUMBER>` auto-closes the issue on merge.
- **Personal Access Token:** Generate it once at `https://git.desineuron.in` → Profile → Settings → Applications → Generate Token. Store it securely (e.g., in your password manager or macOS Keychain).
- **Keep your fork's `main` clean.** Never push feature work directly to `origin/main` — only merge `upstream/main` into it to stay current.