Skip to content

Commit a7326cd

Browse files
salazarsebassalazarsebas
authored
Merge pull request #16 from salazarsebas/chore/verify-project-structure-with-apps-directory
chore: verify project structure with apps directory
2 parents 564fdd7 + 18d12ed commit a7326cd

2 files changed

Lines changed: 309 additions & 24 deletions

File tree

‎apps/backend/README.md‎

Lines changed: 184 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,194 @@
1-
# backend
1+
# Stellar IDE Backend
22

3-
To install dependencies:
3+
## Overview
4+
5+
The backend component of the Stellar IDE provides a secure and efficient server for compiling and testing Rust smart contracts for the Stellar blockchain. Built with Node.js, Express, and TypeScript, it handles code compilation requests from the frontend, executes Rust and Stellar CLI commands in a controlled environment, and returns the results to the user.
6+
7+
## Table of Contents
8+
9+
1. [Architecture](#architecture)
10+
2. [Core Components](#core-components)
11+
3. [Technologies](#technologies)
12+
4. [Setup and Installation](#setup-and-installation)
13+
5. [API Endpoints](#api-endpoints)
14+
6. [Security Measures](#security-measures)
15+
7. [Development Workflow](#development-workflow)
16+
8. [Testing](#testing)
17+
18+
## Architecture
19+
20+
The backend follows a modular architecture with clear separation of concerns:
21+
22+
```mermaid
23+
graph TD
24+
A[Express Server] --> B[Controller Layer]
25+
B --> C[Compilation Service]
26+
B --> D[Testing Service]
27+
C --> E[File System Utils]
28+
D --> E
29+
C --> F[Process Execution Utils]
30+
D --> F
31+
F --> G[Rust Compiler]
32+
F --> H[Stellar CLI]
33+
```
34+
35+
## Core Components
36+
37+
| Component | Description | Responsibility |
38+
|-----------|-------------|----------------|
39+
| **Controllers** | API endpoint handlers | Process HTTP requests and responses |
40+
| **Compilation Service** | Code compilation logic | Manages Rust and WASM compilation workflow |
41+
| **Testing Service** | Test execution logic | Manages test execution and result formatting |
42+
| **File System Utils** | File operations | Handles temporary directories and file I/O |
43+
| **Process Execution** | Command execution | Safely executes shell commands with timeouts |
44+
45+
## Technologies
46+
47+
| Technology | Version | Purpose |
48+
|------------|---------|----------|
49+
| Node.js | 20.x | Runtime environment |
50+
| Express.js | Latest | Web framework |
51+
| TypeScript | Latest | Programming language |
52+
| Bun | Latest | Package manager and runtime |
53+
| Rust | Latest | Smart contract compilation |
54+
| Stellar CLI | Latest | Contract optimization |
55+
56+
## Setup and Installation
57+
58+
### Prerequisites
59+
60+
- Node.js (v20.x or later)
61+
- Bun package manager
62+
- Rust toolchain
63+
- Stellar CLI
64+
- WASM target for Rust
65+
66+
### Installation Steps
467

568
```bash
69+
# Install Rust (if not already installed)
70+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
71+
72+
# Add WASM target
73+
rustup target add wasm32-unknown-unknown
74+
75+
# Install Stellar CLI
76+
cargo install --locked stellar-cli
77+
78+
# Navigate to the backend directory
79+
cd apps/backend
80+
81+
# Install dependencies
682
bun install
83+
84+
# Start the server
85+
bun run src/index.ts
86+
```
87+
88+
The server will start on port 3000 by default (configurable via environment variables).
89+
90+
## API Endpoints
91+
92+
| Endpoint | Method | Description | Request Body | Response |
93+
|----------|--------|-------------|--------------|----------|
94+
| `/api/compile` | POST | Compiles Rust code to WASM | `{ code: string }` | `{ success: boolean, output: string, error?: string }` |
95+
| `/api/test` | POST | Runs tests for Rust code | `{ code: string }` | `{ success: boolean, output: string, error?: string }` |
96+
| `/api/health` | GET | Server health check | None | `{ status: "ok" }` |
97+
98+
## Security Measures
99+
100+
### Input Validation
101+
102+
- All incoming requests are validated for proper structure and content
103+
- Empty or non-string code is rejected
104+
105+
### Command Execution
106+
107+
- Uses `child_process.spawn` instead of `exec` to prevent command injection
108+
- All commands run with strict timeouts (30 seconds by default)
109+
110+
### File System Safety
111+
112+
- Uses `sanitize-filename` for directory names
113+
- Creates isolated temporary directories for each compilation/test request
114+
- Automatically cleans up directories after processing
115+
116+
### API Protection
117+
118+
- Implements Helmet for HTTP header security
119+
- Configures CORS to restrict access to trusted origins
120+
- Rate limiting to prevent abuse
121+
122+
## Development Workflow
123+
124+
### Code Organization
125+
126+
```
127+
backend/
128+
├── src/
129+
│ ├── controllers/
130+
│ │ ├── compile.controller.ts
131+
│ │ └── test.controller.ts
132+
│ ├── utils/
133+
│ │ ├── file.utils.ts
134+
│ │ └── process.utils.ts
135+
│ ├── services/
136+
│ │ ├── compilation.service.ts
137+
│ │ └── testing.service.ts
138+
│ ├── middleware/
139+
│ │ ├── validation.middleware.ts
140+
│ │ └── error.middleware.ts
141+
│ └── index.ts
142+
├── tests/
143+
│ ├── unit/
144+
│ └── integration/
145+
├── tsconfig.json
146+
└── package.json
7147
```
8148

9-
To run:
149+
## Testing
150+
151+
### Unit Tests
10152

11153
```bash
12-
bun run index.ts
154+
bun test
13155
```
14156

15-
This project was created using `bun init` in bun v1.2.19. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
157+
### Integration Tests
158+
159+
```bash
160+
bun test:integration
161+
```
162+
163+
## Performance Considerations
164+
165+
| Aspect | Implementation | Benefit |
166+
|--------|---------------|--------|
167+
| **Concurrency** | Worker threads for compilation | Handles multiple requests efficiently |
168+
| **Caching** | In-memory cache for repeated compilations | Reduces compilation time for identical code |
169+
| **Timeouts** | Configurable command timeouts | Prevents resource exhaustion |
170+
| **Resource Limits** | Memory and CPU constraints | Ensures system stability |
171+
172+
## Error Handling
173+
174+
The backend implements a comprehensive error handling strategy:
175+
176+
1. **Validation Errors**: Returns 400 Bad Request with details
177+
2. **Compilation Errors**: Returns 200 OK with error details in response
178+
3. **System Errors**: Returns 500 Internal Server Error with safe error message
179+
4. **Timeout Errors**: Returns 408 Request Timeout when commands exceed time limit
180+
181+
## Environment Variables
182+
183+
| Variable | Description | Default |
184+
|----------|-------------|--------|
185+
| `PORT` | Server port | 3000 |
186+
| `CORS_ORIGIN` | Allowed CORS origin | http://localhost:4200 |
187+
| `COMMAND_TIMEOUT` | Command execution timeout (ms) | 30000 |
188+
| `MAX_PAYLOAD_SIZE` | Maximum request body size | 1mb |
189+
190+
## Additional Resources
191+
192+
- [Express.js Documentation](https://expressjs.com/)
193+
- [Rust Documentation](https://www.rust-lang.org/learn)
194+
- [Stellar Soroban Documentation](https://developers.stellar.org/)

‎apps/frontend/README.md‎

Lines changed: 125 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,165 @@
1-
# Frontend
1+
# Stellar IDE Frontend
22

3-
This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.1.4.
3+
## Overview
44

5-
## Development server
5+
The frontend component of the Stellar IDE provides a modern, responsive web interface for developers to write, compile, and test Rust smart contracts for the Stellar blockchain. Built with Angular and the Monaco Editor, it offers a professional development experience with syntax highlighting, autocompletion, and real-time feedback.
66

7-
To start a local development server, run:
7+
## Table of Contents
8+
9+
1. [Architecture](#architecture)
10+
2. [Key Components](#key-components)
11+
3. [Technologies](#technologies)
12+
4. [Setup and Installation](#setup-and-installation)
13+
5. [Development Workflow](#development-workflow)
14+
6. [Building and Deployment](#building-and-deployment)
15+
7. [Testing](#testing)
16+
17+
## Architecture
18+
19+
The frontend follows a component-based architecture using Angular's best practices:
20+
21+
```mermaid
22+
graph TD
23+
A[App Component] --> B[Editor Component]
24+
A --> C[Output Component]
25+
B --> D[Monaco Editor]
26+
C --> E[Compilation Results]
27+
C --> F[Test Results]
28+
B <--> G[Backend API Service]
29+
C <--> G
30+
```
31+
32+
## Key Components
33+
34+
| Component | Description | Responsibility |
35+
|-----------|-------------|----------------|
36+
| **Editor Component** | Monaco-based code editor | Provides Rust syntax highlighting, autocompletion, and editing capabilities |
37+
| **Output Component** | Results display panel | Shows compilation/test results with proper formatting |
38+
| **API Service** | Backend communication | Handles HTTP requests to the backend for compilation and testing |
39+
| **Theme Service** | UI theming | Manages dark/light theme preferences |
40+
41+
## Technologies
42+
43+
| Technology | Version | Purpose |
44+
|------------|---------|----------|
45+
| Angular | Latest | Frontend framework |
46+
| TypeScript | Latest | Programming language |
47+
| Monaco Editor | Latest | Code editor component |
48+
| Tailwind CSS | Latest | UI styling |
49+
| RxJS | Latest | Reactive programming |
50+
| Bun | Latest | Package manager |
51+
52+
## Setup and Installation
53+
54+
### Prerequisites
55+
56+
- Node.js (LTS version)
57+
- Bun package manager
58+
- Angular CLI
59+
60+
### Installation Steps
861

962
```bash
10-
ng serve
63+
# Navigate to the frontend directory
64+
cd apps/frontend
65+
66+
# Install dependencies
67+
bun install
68+
69+
# Start development server
70+
bun x ng serve
1171
```
1272

1373
Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files.
1474

15-
## Code scaffolding
75+
## Development Workflow
76+
77+
### Code Organization
78+
79+
```
80+
frontend/
81+
├── src/
82+
│ ├── app/
83+
│ │ ├── components/
84+
│ │ │ ├── editor/
85+
│ │ │ └── output/
86+
│ │ ├── services/
87+
│ │ │ ├── api.service.ts
88+
│ │ │ └── theme.service.ts
89+
│ │ └── app.component.ts
90+
│ ├── assets/
91+
│ └── environments/
92+
├── angular.json
93+
└── package.json
94+
```
95+
96+
### Code Scaffolding
1697

1798
Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
1899

19100
```bash
20-
ng generate component component-name
101+
bun x ng generate component component-name
21102
```
22103

23104
For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
24105

25106
```bash
26-
ng generate --help
107+
bun x ng generate --help
27108
```
28109

29-
## Building
110+
## Building and Deployment
111+
112+
### Development Build
113+
114+
```bash
115+
bun x ng build
116+
```
30117

31-
To build the project run:
118+
### Production Build
32119

33120
```bash
34-
ng build
121+
bun x ng build --configuration production
35122
```
36123

37-
This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed.
124+
This will compile your project and store the build artifacts in the `dist/` directory. The production build optimizes your application for performance and speed.
38125

39-
## Running unit tests
126+
## Testing
127+
128+
### Unit Testing
40129

41130
To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
42131

43132
```bash
44-
ng test
133+
bun x ng test
45134
```
46135

47-
## Running end-to-end tests
136+
### End-to-End Testing
48137

49-
For end-to-end (e2e) testing, run:
138+
For end-to-end (e2e) testing, you can use Cypress or Playwright. To set up Cypress:
50139

51140
```bash
52-
ng e2e
141+
bun add -D cypress
142+
bun x cypress open
53143
```
54144

55-
Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
145+
## User Interface
146+
147+
The Stellar IDE frontend provides a clean, intuitive interface with the following key features:
148+
149+
1. **Code Editor**: Monaco-based editor with Rust syntax highlighting and autocompletion
150+
2. **Action Panel**: Buttons for compiling and testing code
151+
3. **Output Panel**: Displays compilation and test results
152+
4. **Theme Toggle**: Switch between light and dark themes
153+
154+
## Security Considerations
155+
156+
- All user code is validated before sending to the backend
157+
- No sensitive data is stored in local storage
158+
- CORS protection is implemented for API requests
159+
- Content Security Policy (CSP) is configured to prevent XSS attacks
56160

57161
## Additional Resources
58162

59-
For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
163+
- [Angular Documentation](https://angular.dev/)
164+
- [Monaco Editor Documentation](https://microsoft.github.io/monaco-editor/)
165+
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)

0 commit comments

Comments
 (0)