Skip to content

Commit ae7f86a

Browse files
cyclotruccyclotruc
authored
docs: create context.md (#85)
For AI by AI
1 parent f6a21ad commit ae7f86a

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎docs/context.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Pad.ws Developer Onboarding Guide
2+
3+
## Project Overview
4+
5+
Pad.ws is an innovative project that combines a whiteboard canvas with cloud development environments, delivering an "IDE-in-a-whiteboard" experience. The system allows users to seamlessly transition between visual thinking (drawing, diagramming) and coding directly in the browser.
6+
7+
### Key Features
8+
9+
- **Interactive Whiteboard**: Built on a fork of Excalidraw for drawing and visualizing ideas
10+
- **Cloud Development Environment**: Complete development environment accessible from the browser
11+
- **Seamless Workflow**: Switch between ideation and coding in a single interface
12+
- **Collaboration**: Support for collaborative work with backup and versioning
13+
14+
## Architecture Overview
15+
16+
The system follows a microservices architecture with the following components:
17+
18+
```
19+
┌─────────────┐
20+
│ Client │
21+
│ (Browser) │
22+
└──────┬──────┘
23+
│
24+
▼
25+
┌────────────────────────────────────────────────┐
26+
│ FastAPI Backend App │
27+
│ │
28+
│ ┌─────────────┐ ┌────────────────────┐ │
29+
│ │ Static File │ │ API Controllers │ │
30+
│ │ Serving │ │ (routers/*.py) │ │
31+
│ │ (Excalidraw)│ └────────────────────┘ │
32+
│ └─────────────┘ │ │
33+
└─────────────────────────┬──────┼──────────────┘
34+
│ │
35+
│ │
36+
┌─────────────▼──────▼──────────────┐
37+
│ Services │
38+
│ │
39+
┌───────────▼───────┐ ┌─────────▼────────┐ ┌─▼───────────────┐
40+
│ Database │ │ Keycloak │ │ Coder │
41+
│ (PostgreSQL) │ │ (Auth/OIDC) │ │ (Dev Envs) │
42+
└───────────────────┘ └──────────────────┘ └──────────────────┘
43+
│ │ │
44+
│ │ │
45+
▼ ▼ ▼
46+
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
47+
│ Pad Data & │ │ User Auth & │ │ Dev Container │
48+
│ Backups │ │ Sessions │ │ Environments │
49+
└────────────────┘ └────────────────┘ └────────────────┘
50+
```
51+
52+
### Core Components
53+
54+
1. **FastAPI Backend**
55+
- Serves the frontend (Excalidraw fork)
56+
- Handles API requests for pad management
57+
- Manages authentication flow with Keycloak
58+
- Interfaces with Coder API for workspace management
59+
60+
2. **PostgreSQL Database**
61+
- Stores user data, pad content, and backups
62+
- Shared with Keycloak and Coder for their data
63+
64+
3. **Redis**
65+
- Manages user sessions
66+
- Provides caching for performance
67+
- Coordinates distributed operations (like migrations)
68+
69+
4. **Keycloak**
70+
- Provides OIDC authentication
71+
- Manages user accounts and roles
72+
73+
5. **Coder**
74+
- Provisions and manages cloud development environments
75+
- Accessed through the pad's interface
76+
77+
## Code Structure
78+
79+
The repository is structured as follows:
80+
81+
### Backend (`/backend` directory)
82+
83+
```
84+
backend/
85+
├── coder.py # Coder API integration
86+
├── config.py # Configuration and environment variables
87+
├── dependencies.py # FastAPI dependencies
88+
├── main.py # Application entry point
89+
├── requirements.txt # Python dependencies
90+
├── database/ # Database models and operations
91+
│ ├── database.py # Database connection
92+
│ ├── models/ # SQLAlchemy models
93+
│ ├── repository/ # Data access layer
94+
│ └── service/ # Business logic layer
95+
├── routers/ # API routes
96+
│ ├── app_router.py # General app routes
97+
│ ├── auth_router.py # Authentication routes
98+
│ ├── pad_router.py # Pad management routes
99+
│ └── workspace_router.py # Coder workspace routes
100+
└── templates/ # Default pad templates
101+
```
102+
103+
### Key Classes and Components
104+
105+
#### Auth Flow
106+
107+
1. Users authenticate via Keycloak OIDC
108+
2. Session tokens are stored in Redis
109+
3. The `UserSession` class in `dependencies.py` provides access to user information
110+
4. The `auth_router.py` handles login, callback, and logout endpoints
111+
112+
#### Pad Management
113+
114+
1. `PadModel` represents a canvas instance
115+
2. `BackupModel` stores point-in-time backups of pads
116+
3. `TemplatePadModel` provides reusable templates for new pads
117+
4. The Repository pattern is used for data access
118+
5. Service classes implement business logic
119+
120+
#### Coder Integration
121+
122+
The `coder.py` module handles:
123+
1. User management in Coder
124+
2. Workspace creation and provisioning
125+
3. Workspace state management (start/stop)
126+
127+
## Database Schema
128+
129+
The database uses a schema called `pad_ws` with the following tables:
130+
131+
1. **users** - Stores user information
132+
- Synced with Keycloak user data
133+
134+
2. **pads** - Stores canvas/pad data
135+
- Each pad belongs to a user
136+
- Contains the complete state of the canvas
137+
138+
3. **backups** - Stores point-in-time backups of pads
139+
- Automatically created based on time intervals
140+
- Limited to a maximum number per user
141+
142+
4. **template_pads** - Stores reusable templates
143+
- Used when creating new pads
144+
145+
## Development Workflow
146+
147+
1. The FastAPI app serves the Excalidraw frontend at the root route
148+
2. Users interact with the whiteboard interface
149+
3. Canvas data is periodically saved to the backend
150+
4. When a user accesses development features, their Coder workspace is started
151+
5. The UI integrates the dev environment within the whiteboard
152+
153+
## Getting Started
154+
155+
1. Follow the self-hosting instructions in the README to set up the development environment
156+
2. The `.env` file contains configuration for all services
157+
3. For local development, you can use `docker-compose` to run the dependencies (PostgreSQL, Redis, Keycloak, Coder)
158+
4. Run the FastAPI app with `uvicorn main:app --reload` for local development
159+
160+
## Key APIs and Endpoints
161+
162+
- `/auth/*` - Authentication endpoints
163+
- `/api/pad/*` - Canvas/pad management
164+
- `/api/workspace/*` - Coder workspace management
165+
- `/api/users/*` - User management
166+
- `/api/templates/*` - Template management
167+
168+
## Additional Resources
169+
170+
- Excalidraw documentation: https://github.com/excalidraw/excalidraw
171+
- Coder documentation: https://coder.com/docs/
172+
- FastAPI documentation: https://fastapi.tiangolo.com/
173+
- SQLAlchemy documentation: https://docs.sqlalchemy.org/

0 commit comments

Comments
 (0)