Skip to content

Commit 9997caf

Browse files
ogazboizogazboiz
authored
Merge pull request #159 from 0xVida/issue135
feat: Backend: API Versioning Strategy
2 parents d846ecf + aa87df6 commit 9997caf

33 files changed

Lines changed: 9034 additions & 4344 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: Bug Report
3+
about: Create a report to help us improve
4+
title: '[BUG] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Description
10+
A clear and concise description of what the bug is.
11+
12+
## Steps to Reproduce
13+
1. Go to '...'
14+
2. Click on '....'
15+
3. Scroll down to '....'
16+
4. See error
17+
18+
## Expected Behavior
19+
A clear and concise description of what you expected to happen.
20+
21+
## Actual Behavior
22+
A clear and concise description of what actually happened.
23+
24+
## Screenshots
25+
If applicable, add screenshots to help explain your problem.
26+
27+
## Environment
28+
- **FlowFi Version**: (e.g., commit hash or version number)
29+
- **Browser**: (e.g., Chrome 120, Firefox 121)
30+
- **Operating System**: (e.g., macOS 14.2, Ubuntu 22.04)
31+
- **Node.js Version**: (if relevant)
32+
- **Wallet**: (e.g., Freighter 2.0.0)
33+
34+
## Component
35+
- [ ] Frontend
36+
- [ ] Backend
37+
- [ ] Smart Contracts
38+
- [ ] Documentation
39+
- [ ] Other (please specify)
40+
41+
## Logs/Error Messages
42+
```
43+
Paste any relevant logs or error messages here
44+
```
45+
46+
## Additional Context
47+
Add any other context about the problem here.
48+
49+
## Possible Solution
50+
If you have ideas on how to fix this, please describe them here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for FlowFi
4+
title: '[FEATURE] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Feature Description
10+
A clear and concise description of the feature you'd like to see.
11+
12+
## Problem Statement
13+
What problem does this feature solve? What use case does it address?
14+
15+
## Proposed Solution
16+
Describe how you envision this feature working.
17+
18+
## Alternatives Considered
19+
Describe any alternative solutions or features you've considered.
20+
21+
## Component
22+
- [ ] Frontend
23+
- [ ] Backend
24+
- [ ] Smart Contracts
25+
- [ ] Documentation
26+
- [ ] Other (please specify)
27+
28+
## Additional Context
29+
Add any other context, mockups, or examples about the feature request here.
30+
31+
## Implementation Notes
32+
If you have technical ideas about how this could be implemented, please share them here.

‎.github/pull_request_template.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
## Description
2+
<!-- Provide a clear and concise description of what this PR does -->
3+
4+
## Type of Change
5+
<!-- Mark the relevant option with an 'x' -->
6+
7+
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
8+
- [ ] ✨ New feature (non-breaking change which adds functionality)
9+
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
10+
- [ ] 📚 Documentation update
11+
- [ ] 🔧 Refactoring (no functional changes)
12+
- [ ] ⚡ Performance improvement
13+
- [ ] 🧪 Test addition or update
14+
15+
## Related Issues
16+
<!-- Link related issues using keywords like "Closes", "Fixes", "Resolves" -->
17+
<!-- Example: Closes #123, Fixes #456 -->
18+
19+
Closes #
20+
21+
## Changes Made
22+
<!-- Describe the specific changes made in this PR -->
23+
24+
## Testing
25+
<!-- Describe the tests you ran and how to verify your changes -->
26+
27+
### Test Coverage
28+
- [ ] Unit tests added/updated
29+
- [ ] Integration tests added/updated
30+
- [ ] Manual testing performed
31+
32+
### Test Steps
33+
<!-- If applicable, provide steps to test the changes -->
34+
1.
35+
2.
36+
3.
37+
38+
## Breaking Changes
39+
<!-- If this PR includes breaking changes, describe them here -->
40+
<!-- If none, you can remove this section -->
41+
42+
**Breaking Changes:**
43+
-
44+
45+
**Migration Guide:**
46+
<!-- If applicable, provide steps for users to migrate -->
47+
48+
## Screenshots/Demo
49+
<!-- If applicable, add screenshots or a link to a demo -->
50+
51+
## Checklist
52+
<!-- Mark completed items with an 'x' -->
53+
54+
- [ ] My code follows the project's style guidelines
55+
- [ ] I have performed a self-review of my own code
56+
- [ ] I have commented my code, particularly in hard-to-understand areas
57+
- [ ] I have made corresponding changes to the documentation
58+
- [ ] My changes generate no new warnings
59+
- [ ] I have added tests that prove my fix is effective or that my feature works
60+
- [ ] New and existing unit tests pass locally with my changes
61+
- [ ] Any dependent changes have been merged and published
62+
- [ ] I have checked for breaking changes and documented them if applicable
63+
64+
## Additional Notes
65+
<!-- Any additional information that reviewers should know -->

‎CONTRIBUTING.md‎

Lines changed: 138 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -107,45 +107,173 @@ docker compose down -v
107107

108108
## Option 2: Manual Setup
109109

110-
### Backend
110+
### Backend Setup
111+
112+
1. **Install Dependencies**
111113

112114
```bash
113115
cd backend
114116
npm install
115-
npm run dev
116117
```
117118

118-
Backend runs on:
119+
2. **Set Up Database**
120+
121+
The backend uses PostgreSQL. You can either:
122+
- Use Docker Compose (recommended): `docker compose up postgres -d`
123+
- Or set up PostgreSQL locally and configure `DATABASE_URL` in your `.env` file
119124

125+
3. **Run Database Migrations**
126+
127+
```bash
128+
npm run prisma:generate
129+
npm run prisma:migrate
120130
```
121-
http://localhost:3001
131+
132+
4. **Start Development Server**
133+
134+
```bash
135+
npm run dev
122136
```
123137

138+
Backend runs on: `http://localhost:3001`
139+
140+
**Available Backend Scripts:**
141+
- `npm run dev` - Start development server with hot reload
142+
- `npm run build` - Build TypeScript to JavaScript
143+
- `npm run start` - Start production server
144+
- `npm run test` - Run test suite
145+
- `npm run prisma:generate` - Generate Prisma client
146+
- `npm run prisma:migrate` - Run database migrations
147+
- `npm run prisma:studio` - Open Prisma Studio (database GUI)
148+
149+
**Backend API Documentation:**
150+
- Swagger UI: `http://localhost:3001/api-docs`
151+
- OpenAPI Spec: `http://localhost:3001/api-docs.json`
152+
124153
---
125154

126-
### 2️ Frontend
155+
### Frontend Setup
156+
157+
1. **Install Dependencies**
127158

128159
```bash
129160
cd frontend
130161
npm install
131-
npm run dev
132162
```
133163

134-
Frontend runs on:
164+
2. **Start Development Server**
135165

136-
```
137-
http://localhost:3000
166+
```bash
167+
npm run dev
138168
```
139169

170+
Frontend runs on: `http://localhost:3000`
171+
172+
**Available Frontend Scripts:**
173+
- `npm run dev` - Start Next.js development server
174+
- `npm run build` - Build for production
175+
- `npm run start` - Start production server
176+
- `npm run lint` - Run ESLint
177+
178+
**Environment Variables:**
179+
Create a `.env.local` file in the `frontend` directory if needed for API endpoints or other configuration.
180+
140181
---
141182

142-
### 3️ Smart Contracts
183+
### Smart Contracts Setup
184+
185+
1. **Install Rust Toolchain**
186+
187+
Make sure you have Rust and Cargo installed. If not:
188+
189+
```bash
190+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
191+
```
192+
193+
2. **Install Soroban CLI** (if not already installed)
194+
195+
```bash
196+
cargo install --locked soroban-cli
197+
```
198+
199+
3. **Build Contracts**
143200

144201
```bash
145202
cd contracts
146203
cargo build --target wasm32-unknown-unknown --release
147204
```
148205

206+
The compiled WASM files will be in `target/wasm32-unknown-unknown/release/`.
207+
208+
**Contract Development:**
209+
- Contract source: `contracts/stream_contract/src/lib.rs`
210+
- Tests: `contracts/stream_contract/src/test.rs`
211+
- Build target: `wasm32-unknown-unknown`
212+
213+
---
214+
215+
## Development Scripts & Tools
216+
217+
### Root-Level Scripts
218+
219+
From the repository root:
220+
221+
```bash
222+
# Verify security setup
223+
npm run verify-security
224+
```
225+
226+
### Docker Compose Commands
227+
228+
```bash
229+
# Start all services
230+
docker compose up --build
231+
232+
# Start in detached mode
233+
docker compose up -d --build
234+
235+
# View logs
236+
docker compose logs -f
237+
238+
# Stop services
239+
docker compose down
240+
241+
# Reset database (removes volumes)
242+
docker compose down -v
243+
```
244+
245+
---
246+
247+
## CI/CD Workflows
248+
249+
This repository uses GitHub Actions for continuous integration. Workflows are located in `.github/workflows/`.
250+
251+
### Available Workflows
252+
253+
- **Security Checks** (`.github/workflows/security.yml`)
254+
- Runs on: push to `main`/`develop`, pull requests, and weekly schedule
255+
- Performs:
256+
- Dependency vulnerability scanning (`npm audit`)
257+
- CodeQL analysis for JavaScript/TypeScript
258+
- View workflow: [Security Checks](.github/workflows/security.yml)
259+
260+
### Running CI Checks Locally
261+
262+
Before pushing, ensure your changes pass:
263+
264+
```bash
265+
# Frontend linting
266+
cd frontend && npm run lint
267+
268+
# Backend tests
269+
cd backend && npm run test
270+
271+
# Security verification
272+
npm run verify-security
273+
```
274+
275+
For more details, see the [Security Workflow](.github/workflows/security.yml).
276+
149277
---
150278

151279
# Branching Strategy

‎README.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,20 @@ flowfi/
2222
├── contracts/ # Soroban smart contracts
2323
│ ├── stream_contract/ # Core streaming logic
2424
├── frontend/ # Next.js + Tailwind CSS frontend
25+
├── docs/ # Documentation
26+
│ └── ARCHITECTURE.md # Architecture overview
2527
```
2628

29+
## Architecture
30+
31+
FlowFi consists of three main components that work together:
32+
33+
- **Soroban Smart Contracts**: Handle on-chain payment stream logic
34+
- **Backend API**: Indexes on-chain events, provides REST API, and streams real-time updates via SSE
35+
- **Frontend**: User interface for creating and managing payment streams
36+
37+
For a detailed explanation of how these components interact, where event indexing happens, and the overall system architecture, see the [Architecture Documentation](docs/ARCHITECTURE.md).
38+
2739
## Getting Started
2840

2941
### Prerequisites
@@ -83,9 +95,23 @@ cd contracts
8395
cargo build --target wasm32-unknown-unknown --release
8496
```
8597

98+
## API Documentation
99+
100+
The FlowFi backend API uses URL-based versioning. All endpoints are prefixed with a version (e.g., `/v1/streams`).
101+
102+
- **API Versioning Guide**: [backend/docs/API_VERSIONING.md](backend/docs/API_VERSIONING.md)
103+
- **Deprecation Policy**: [backend/docs/DEPRECATION_POLICY.md](backend/docs/DEPRECATION_POLICY.md)
104+
- **API Docs**: Available at `http://localhost:3001/api-docs` when backend is running
105+
86106
## Contributing
87107

88-
Contributions are welcome! Please fork the repository and submit a pull request.
108+
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for:
109+
- Local development setup instructions
110+
- Code style and commit guidelines
111+
- Pull request process
112+
- Development scripts and CI workflows
113+
114+
For architecture details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
89115

90116
## Security
91117

0 commit comments

Comments
 (0)