Skip to content

Refactor installation commands and add AI coding guide for Splitwiser project #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Devasy merged 2 commits into from
Jul 22, 2025
Merged

Refactor installation commands and add AI coding guide for Splitwiser project #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d7e2fe8
refactor(nixpacks): streamline installation commands and enhance buil…
Devasy Jul 22, 2025
5f949d2
docs: Add AI coding guide for Splitwiser project
Devasy Jul 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Splitwiser - AI Coding Guide

This document provides essential context for AI assistants working with the Splitwiser codebase.

## Project Overview

Splitwiser is an expense tracking and splitting application with:
- Backend: FastAPI + MongoDB
- Frontend POC: Streamlit
- Planned Frontend: Expo/React Native (in development)

The app allows users to create groups, add expenses with flexible splitting options, track balances, and handle settlements.

## Architecture

### Backend (FastAPI)
- Located in `/backend/`
- RESTful API using FastAPI with Python 3.9+
- MongoDB for database (nonrelational schema)
Comment on lines +17 to +19
Copy link
Contributor

@coderabbitai coderabbitai bot Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Python version mismatch between docs and build configuration.

Docs say “Python 3.9+” while nixpacks.toml pins 3.12. Align them to avoid on-boarding confusion and runtime surprises (e.g., 3.12 deprecations).

🤖 Prompt for AI Agents 
In .github/copilot-instructions.md around lines 17 to 19, the Python version
mentioned in the documentation is "Python 3.9+" but the build configuration in
nixpacks.toml pins Python 3.12. Update the documentation to reflect Python 3.12
to ensure consistency and avoid confusion during onboarding and runtime issues.

- JWT authentication with refresh token rotation
- Modular design with services:
- `app/auth/`: Authentication & user registration
- `app/user/`: User profile management
- `app/groups/`: Group creation & management
- `app/expenses/`: Expense tracking & splitting

### Frontend POC (Streamlit)
- Located in `/ui-poc/`
- `Home.py`: Entry point with login/registration
- `pages/`: Contains main application pages
- `Groups.py`: Group management & expense creation
- `Friends.py`: Friend balance tracking

## Key Development Patterns

### API Communication
```python
# Example API call with retry logic from Groups.py
response = make_api_request(
method="get",
url=f"{API_URL}/groups/{group_id}",
headers={"Authorization": f"Bearer {st.session_state.access_token}"},
max_retries=3
)
```

### State Management
- Backend: MongoDB stores persistent data
- Frontend: Streamlit session state manages user session
```python
# Session state initialization (see Home.py)
if "access_token" not in st.session_state:
st.session_state.access_token = None
```

### Expense Handling
- Support for different split types: equal, unequal, percentage-based
- Each expense has a payer and multiple splits (recipients)
- Settlements track debt resolution between users

## Developer Workflows

### Setup & Running
1. Backend:
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload
```
2. Frontend POC:
```bash
cd ui-poc
pip install -r requirements.txt
streamlit run Home.py
```
3. Test Data Generation:
```bash
cd ui-poc
python setup_test_data.py
```

### Testing
- Backend tests in `/backend/tests/`
- Run tests with: `cd backend && pytest`
- Test data setup script: `/ui-poc/setup_test_data.py`

## Critical Files & Dependencies

- `backend/main.py`: Main FastAPI application entry point
- `backend/app/config.py`: Configuration settings
- `backend/app/database.py`: MongoDB connection
- `ui-poc/Home.py`: Streamlit application entry point
- `ui-poc/openapi.json`: API specification for frontend reference

## Common Tasks

- Adding new API endpoint: Add route to appropriate service router file
- Adding new UI component: Modify files in `/ui-poc/pages/`
- Testing data flow: Use the `setup_test_data.py` to create test scenarios
- Troubleshooting auth: Check JWT token handling in `app/auth/security.py`
18 changes: 5 additions & 13 deletions nixpacks.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,17 @@
[phases.setup]
nixPkgs = ["python312", "pip"]

# Completely override the install command to avoid duplicate processes
# Use the default Python install behavior but ensure we use the right requirements file
[phases.install]
cmds = [
"python -m pip install --upgrade pip",
"pip install --upgrade pip",
"pip install -r requirements.txt"
]

# Skip Python's default install phase entirely
[phases.python:install]
dependsOn = ["install"]
cmds = []

[phases.build]
cmds = [
"echo 'Build phase complete'",
# Copy backend files to the root for simpler execution
"cp -r backend/* ."
"echo 'Build phase: Copying backend files'",
"cp -r backend/* . || echo 'Backend files already in place'"
]
Comment on lines +13 to 15
Copy link
Contributor

@coderabbitai coderabbitai bot Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

cp -r backend/* . drops dotfiles and returns a non-zero exit when the folder is absent.

  1. Dot-files such as .env.example will not be copied because of shell globbing rules.
  2. If backend/ is missing (e.g., a shallow checkout), cp exits with 1, and the echo that follows masks the failure but still pollutes the logs.

A safer, idempotent alternative:

-"cp -r backend/* . || echo 'Backend files already in place'"
+"shopt -s dotglob && cp -R backend/* . 2>/dev/null || echo 'No backend directory to copy'"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"echo 'Build phase: Copying backend files'",
"cp -r backend/* . || echo 'Backend files already in place'"
]
"echo 'Build phase: Copying backend files'",
"shopt -s dotglob && cp -R backend/* . 2>/dev/null || echo 'No backend directory to copy'"
]
🤖 Prompt for AI Agents 
In nixpacks.toml around lines 13 to 15, the command `cp -r backend/* .` fails to
copy dotfiles and returns a non-zero exit code if the backend directory is
missing, causing misleading logs. Replace this with a command that copies all
files including dotfiles safely and checks for the existence of the backend
directory before copying to avoid errors and ensure idempotency.


[start]
Expand All @@ -28,7 +22,5 @@ cmd = "uvicorn main:app --host 0.0.0.0 --port $PORT"
PYTHONPATH = "/app"
PYTHONUNBUFFERED = "1"

# Specify we're using plain pip without a venv
# Let Nixpacks handle virtual environment creation automatically
[nixpacks]
plan-path = "disabled"
create-venv = false