Skip to content

Commit 615369f

Browse files
UncleSamSwissUncleSamSwiss
authored
Merge pull request #111 from ioBroker/copilot/fix-110
✨ Set up Copilot instructions for repository
2 parents 26b8a51 + fb5b5ea commit 615369f

File tree

1 file changed

+233
-0
lines changed

1 file changed

+233
-0
lines changed

‎.copilot-instructions.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Copilot Instructions for ioBroker Developer Portal
2+
3+
## Project Overview
4+
5+
This repository contains the **ioBroker Developer Portal** (https://www.iobroker.dev), a comprehensive web application that provides tools and resources for ioBroker adapter developers. ioBroker is a home automation platform, and this portal helps developers create, manage, and publish adapters (plugins) for the platform.
6+
7+
## Key Features
8+
9+
- **Adapter Creator Tool**: Wizard-based tool for generating new ioBroker adapter projects
10+
- **Adapter Management**: Tools for managing existing adapters, releases, and translations
11+
- **Developer Resources**: Documentation, best practices, and community links
12+
- **GitHub Integration**: OAuth-based authentication and repository management
13+
- **Weblate Integration**: Translation management for adapters
14+
- **Statistics and Analytics**: Adapter usage and development insights
15+
16+
## Technology Stack
17+
18+
### Frontend
19+
- **React 18** with TypeScript
20+
- **Material-UI (MUI) v6** for components and theming
21+
- **React Router** for client-side routing
22+
- **Axios** for API communication
23+
- **React Context** for state management
24+
- **ECharts** for data visualization
25+
- **WebSocket** for real-time communication
26+
27+
### Backend
28+
- **Node.js** with **Express.js**
29+
- **TypeScript** for type safety
30+
- **MongoDB** for data storage
31+
- **WebSocket (ws)** for real-time features
32+
- **GitHub API** integration via Octokit
33+
- **Cron jobs** for scheduled tasks
34+
- **Docker** for containerization
35+
36+
### Development Environment
37+
- **DevContainers** with VS Code integration
38+
- **Docker Compose** for orchestration
39+
- **Hot reload** for both frontend and backend
40+
- **Prettier** and **ESLint** for code formatting
41+
- **GitHub Copilot** integration
42+
43+
## Repository Structure
44+
45+
```
46+
├── .devcontainer/ # DevContainer configuration
47+
├── .github/ # GitHub workflows and configurations
48+
├── express/ # Main application directory
49+
│ ├── backend/ # Express.js backend
50+
│ │ ├── src/ # TypeScript source code
51+
│ │ │ ├── api/ # API route handlers
52+
│ │ │ ├── apps/ # Application-specific logic
53+
│ │ │ ├── auth.ts # Authentication handling
54+
│ │ │ └── index.ts # Main server entry point
55+
│ │ └── package.json # Backend dependencies
56+
│ └── frontend/ # React frontend
57+
│ ├── src/ # React TypeScript source
58+
│ │ ├── components/ # Reusable UI components
59+
│ │ ├── contexts/ # React Context providers
60+
│ │ ├── tools/ # Feature-specific tools
61+
│ │ └── App.tsx # Main React component
62+
│ └── package.json # Frontend dependencies
63+
├── docker-compose.yml # Development orchestration
64+
└── README.md # Project documentation
65+
```
66+
67+
## Code Style and Conventions
68+
69+
### Formatting (Prettier Configuration)
70+
- **Use tabs** for indentation (tabWidth: 4)
71+
- **80 character** line width
72+
- **Semicolons required**
73+
- **Double quotes** for strings
74+
- **Trailing commas** in all multi-line structures
75+
- **LF line endings**
76+
77+
### TypeScript Conventions
78+
- **Strict mode** enabled for both frontend and backend
79+
- **Explicit typing** preferred over `any`
80+
- **Interface definitions** for all object shapes
81+
- **Functional components** with hooks in React
82+
- **Context providers** for shared state
83+
84+
### File Naming
85+
- **PascalCase** for React components (`UserContext.tsx`)
86+
- **camelCase** for utility files (`auth.ts`)
87+
- **kebab-case** for directories when appropriate
88+
- **Descriptive names** that indicate purpose
89+
90+
### Component Patterns
91+
- Use **function declarations** for React components
92+
- **Export at declaration** for main components
93+
- **Props interfaces** defined above components
94+
- **Context providers** for cross-component state
95+
- **Custom hooks** for reusable logic
96+
97+
## Development Setup
98+
99+
### Requirements
100+
- **VS Code** with DevContainer support
101+
- **Docker** and **Docker Compose**
102+
- **Git** for version control
103+
104+
### Getting Started
105+
1. Clone the repository
106+
2. Open in VS Code
107+
3. Reopen in DevContainer when prompted
108+
4. Frontend and backend will start automatically
109+
5. Access the application at `http://localhost:8080`
110+
111+
### Environment Variables
112+
The application requires several environment variables for full functionality:
113+
114+
**Required:**
115+
- `PORTAL_GITHUB_OAUTH_CLIENT_ID` - GitHub OAuth for portal
116+
- `PORTAL_GITHUB_OAUTH_CLIENT_SECRET` - GitHub OAuth secret
117+
- `CREATOR_GITHUB_OAUTH_CLIENT_ID` - GitHub OAuth for adapter creator
118+
- `CREATOR_GITHUB_OAUTH_CLIENT_SECRET` - GitHub OAuth secret
119+
120+
**Optional:**
121+
- `WEBLATE_ACCESS_TOKEN` - For translation management
122+
- `SENTRY_AUTH_TOKEN` - For error tracking
123+
- `ALLOW_CORS` - Enable CORS for development
124+
125+
## Key Concepts and Domain Knowledge
126+
127+
### ioBroker Ecosystem
128+
- **Adapters** are plugins that extend ioBroker functionality
129+
- **Instances** are running copies of adapters
130+
- **Objects** represent devices, states, and configuration
131+
- **States** hold current values and can be read/written
132+
- **Repository** system for adapter distribution
133+
134+
### Adapter Development Workflow
135+
1. **Create** adapter using the Creator Tool
136+
2. **Develop** using ioBroker patterns and APIs
137+
3. **Test** locally and with automated tools
138+
4. **Translate** using Weblate integration
139+
5. **Release** and publish to npm
140+
6. **Submit** to ioBroker repository for review
141+
142+
### Common Patterns
143+
- **GitHub OAuth** authentication for repository access
144+
- **WebSocket** communication for real-time updates
145+
- **Token management** for GitHub and npm access
146+
- **ZIP generation** for adapter scaffolding
147+
- **MongoDB** document storage patterns
148+
149+
## API Patterns
150+
151+
### Backend Routes
152+
- `/api/user/*` - User authentication and management
153+
- `/api/adapter/*` - Adapter-related operations
154+
- `/api/weblate/*` - Translation proxy
155+
- `/api/npm/*` - npm registry proxy
156+
- `/apps/create-adapter` - Adapter creation tool
157+
158+
### Frontend Structure
159+
- **Context providers** for global state
160+
- **Tool-specific** route handling
161+
- **Material-UI** component composition
162+
- **Axios** with interceptors for API calls
163+
164+
## Testing and Quality
165+
166+
### Frontend Testing
167+
- **React Testing Library** for component tests
168+
- **Jest** as test runner
169+
- Run with: `npm test` in frontend directory
170+
171+
### Code Quality
172+
- **TypeScript** strict mode for type safety
173+
- **ESLint** for code quality (React app configuration)
174+
- **Prettier** for consistent formatting
175+
- **GitHub Actions** for CI/CD
176+
177+
## Deployment
178+
179+
### Development
180+
- Uses **DevContainers** with automatic startup
181+
- **Hot reload** for both frontend and backend
182+
- **Proxy** routes frontend requests to backend
183+
184+
### Production
185+
- **Docker Compose** orchestration
186+
- **GitHub Container Registry** for images
187+
- **Environment-based** configuration
188+
- **Watchtower** for automatic updates
189+
190+
## Important Notes for AI Assistance
191+
192+
1. **Preserve ioBroker context** - This is domain-specific software for home automation
193+
2. **GitHub integration is critical** - Many features depend on GitHub API access
194+
3. **Material-UI patterns** - Use MUI components and theming consistently
195+
4. **TypeScript strict mode** - Always provide proper type definitions
196+
5. **DevContainer workflow** - Development should work seamlessly in containers
197+
6. **Adapter creation focus** - Core functionality is helping developers build adapters
198+
7. **Translation support** - Consider internationalization in new features
199+
8. **Real-time features** - WebSocket connections are used for live updates
200+
201+
## When Making Changes
202+
203+
- **Test in DevContainer** environment to ensure consistency
204+
- **Follow TypeScript** strict typing requirements
205+
- **Use Material-UI** components for UI consistency
206+
- **Consider mobile** responsiveness for all UI changes
207+
- **Maintain GitHub** OAuth integration patterns
208+
- **Update documentation** when adding new features
209+
- **Consider translation** needs for user-facing text
210+
- **Test adapter creation** workflow if modifying related code
211+
212+
## Helpful Commands
213+
214+
```bash
215+
# Start development environment
216+
docker-compose up
217+
218+
# Frontend commands (in express/frontend/)
219+
npm start # Start development server
220+
npm run build # Build for production
221+
npm test # Run tests
222+
223+
# Backend commands (in express/backend/)
224+
npm run watch # Start with hot reload
225+
npm run build # Compile TypeScript
226+
npm run watch:debug # Start with debugger
227+
228+
# Docker commands
229+
docker-compose pull && docker-compose up # Update and start
230+
docker login docker.pkg.github.com # Login to GitHub registry
231+
```
232+
233+
This portal is a critical tool for the ioBroker community, helping developers create high-quality adapters that extend the platform's capabilities for home automation enthusiasts worldwide.

0 commit comments

Comments
 (0)