Skip to content

Commit a6f129f

Browse files
Zaira BibiZaira Bibi
Zaira Bibi
authored and
Zaira Bibi
committed
feat: initial backend setup with api and core packages
Set up the backend structure with two main crates: - `api/`: Axum-based HTTP server for serving RESTful APIs - `core/`: Library crate containing database logic using Diesel and PostgreSQL Also updated Cargo workspace structure to include new packages and documented the new project layout, purpose of each component and build instructions in README. No application logic or endpoints are implemented yet.
1 parent 06204b0 commit a6f129f

File tree

10 files changed

+357
-126
lines changed

10 files changed

+357
-126
lines changed

‎Cargo.lock‎

Lines changed: 104 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ resolver = "3"
33

44
members = [
55
"mcp",
6+
"backend/api",
7+
"backend/core",
68
]
79

810
[workspace.package]

‎README.md‎

Lines changed: 7 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,11 @@
33
Sparkth is a free, open source, extensible, science-driven, AI-first learning platform. It is under active development by
44
[Edly](https://edly.io).
55

6-
With Sparkth, users can create create courses from the chat UI of AI providers such as Claude or ChatGPT. Integration with these generative AI providers is achieved by the Model Context Protocol ([MCP](https://modelcontextprotocol.io/)) standard.
7-
8-
**Features**:
9-
10-
- Filter/Event API for extensive customisation of Sparkth.
11-
- MCP endpoints that make it possible to use Sparkth as an external tool in Claude/ChatGPT/Gemini.
12-
- Course generation prompt template that follows good instructional design principles.
13-
- Synchronization of generated course content with 3rd-party learning management systems (LMS), such as [Canvas](https://canvas.instructure.com/).
14-
15-
**Tool Development Guide**:
16-
17-
The tool development guide can be found [here](src/plugins/README.md).
6+
This repository is organized as a [Cargo workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) with three main components:
187

8+
- `mcp/`: a binary crate that runs the MCP server, responsible for creating courses from the chat UI of AI providers
9+
- `backend/api/`: a binary crate that serves HTTP APIs
10+
- `backend/core/`: a library crate for database access (PostgreSQL via Diesel)
1911

2012
**Roadmap**:
2113

@@ -61,120 +53,11 @@ chmod a+x sparkth
6153

6254
### Building
6355

64-
Make sure that you have the following requirements:
65-
66-
- Rust ([documentation](https://doc.rust-lang.org/book/ch01-01-installation.html)):
67-
68-
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
69-
70-
- uvx, for MCP integration ([documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)):
71-
72-
curl -LsSf https://astral.sh/uv/install.sh | sh
73-
74-
Checkout the code:
75-
76-
git clone git@github.com:edly-io/sparkth.git
77-
cd sparkth
78-
79-
Build the application:
80-
81-
cargo build --release
82-
83-
The compiled executable will be in `target/release`. Run Sparkth with:
84-
85-
cargo run --release --
86-
87-
Any CLI option supported by Sparkth can be appended to this command.
88-
89-
## Docker
90-
91-
A pre-built Docker image for Sparkth is published automatically to the GitHub Container Registry on each push to the `main` branch.
92-
93-
Pull the [`ghcr.io/edly-io/sparkth:latest`](https://github.com/edly-io/sparkth/pkgs/container/sparkth) image with:
94-
95-
docker pull ghcr.io/edly-io/sparkth:latest
96-
97-
Alternatively, build the image manually with:
98-
99-
docker build -t ghcr.io/edly-io/sparkth:latest .
100-
101-
Then, run the Sparkth MCP server with:
102-
103-
# Expose MCP server to http://localhost:7727
104-
docker run \
105-
--env CANVAS_API_URL=https://canvas.instructure.com/api/v1 \
106-
--env CANVAS_API_TOKEN=<your canvas API key> \
107-
--publish 127.0.0.1:7727:7727 \
108-
ghcr.io/edly-io/sparkth:latest
56+
The build guides are provided here:
10957

110-
Any CLI option supported by Sparkth can be appended to this command.
58+
1. MCP [documentation](/mcp/README.md)
59+
2. Backend [documentation](/backend/README.md)
11160

112-
## Usage
113-
114-
### Local usage
115-
116-
Add the `sparkth` (or `sparkth.exe`) executable as an external tool to Claude Desktop by editing the Claude configuration file:
117-
118-
# macOS
119-
~/Library/Application\ Support/Claude/claude_desktop_config.json
120-
# Windows
121-
%APPDATA%\Claude\claude_desktop_config.json
122-
# Linux
123-
~/.config/Claude/claude_desktop_config.json
124-
125-
Add the Sparkth server, such that your configuration looks like the following:
126-
127-
{
128-
"mcpServers": {
129-
"Sparkth stdio": {
130-
"command": "/<PATH TO SPARKTH REPOSITORY>/target/release/sparkth",
131-
"args": ["--mode=stdio"],
132-
"env": {
133-
"CANVAS_API_URL": "https://canvas.instructure.com/api/v1",
134-
"CANVAS_API_TOKEN": "<your canvas API key>"
135-
}
136-
}
137-
}
138-
}
139-
140-
Restart Claude Desktop. Ensure that the "Sparkth stdio" tools appear in the "Search and tools" menu. Then start a new chat and generate a course:
141-
142-
> Use Sparkth to generate a very short course (~1 hour) on the literary merits of Hamlet, by Shakespeare.
143-
144-
Sparkth will generate a prompt that will help Claude generate this course.
145-
146-
### Production deployment
147-
148-
Deploying Sparkth in production involves the following steps:
149-
150-
1. Run Sparkth in SSE mode, either with Docker or a pre-built image.
151-
2. Run an HTTPS proxy, for instance [Caddy](https://caddyserver.com/) with self-generated SSL certificates.
152-
3. Add the Sparkth MCP server in Claude: Settings 🠂 Connectors 🠂 Add custom connector:
153-
154-
Name=Sparkth SSE
155-
Remote MCP server URL=https://<yourdomainname.com>/
156-
157-
### Options
158-
159-
#### Transport mode: server-sent events (SSE) / stdio
160-
161-
Sparkth MCP server can run in two modes, selectable via the `--mode` flag:
162-
163-
| Mode | Description |
164-
| ------- | ---------------------------------------------------- |
165-
| `stdio` | Communicates via standard input/output streams. |
166-
| `sse` | Starts an HTTP server with Server-Sent Events. |
167-
168-
The default is `sse` on host http://0.0.0.0:7727.
169-
170-
This starts an SSE server on the given host and port with:
171-
172-
* `GET /` for establishing the event stream.
173-
* `POST /message` for sending messages.
174-
175-
The `stdio` transport mode is appropriate for running with Claude locally:
176-
177-
./sparkth --mode=stdio
17861

17962
## Development
18063

@@ -186,8 +69,6 @@ Run tests:
18669

18770
cargo test
18871

189-
⚠️ Note that in stdio mode, you will need to restart Claude Desktop every time you recompile, otherwise changes will not be automatically picked up.
190-
19172
## License
19273

19374
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

‎backend/.env.example‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Example Environment Configuration
2+
3+
# PostgreSQL connection URL.
4+
# Format: postgres://USER:PASSWORD@HOST:PORT/DATABASE_NAME
5+
# Example: postgres://postgres:password@localhost:5432/mydb
6+
PG_DATABASE_URL=
7+
8+
# Typically 0.0.0.0 for all interfaces or 127.0.0.1 for local only.
9+
# Example: 127.0.0.1
10+
HOST=
11+
12+
# Port number for the backend server to listen on.
13+
# Example: 8000
14+
PORT=

‎backend/README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Sparkth Backend
2+
3+
Sparkth is a free, open source, extensible, science-driven, AI-first learning platform. It is under active development by [Edly](https://edly.io/).
4+
5+
This repository is organized as a [Cargo workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) with two main components:
6+
7+
- `core/`: a library crate for database access (PostgreSQL via Diesel)
8+
- `api/`: a binary crate that serves HTTP APIs
9+
10+
## Prerequisites
11+
12+
Before building or running the project, make sure you have the following installed:
13+
14+
- Rust ([documentation](https://doc.rust-lang.org/book/ch01-01-installation.html)):
15+
16+
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
17+
18+
- [PostgreSQL](https://www.postgresql.org/) (local or remote)
19+
- [libpq](https://www.postgresql.org/docs/current/libpq.html) (PostgreSQL client library, required by Diesel)
20+
- [diesel_cli](https://diesel.rs/guides/getting-started#installing-diesel-cli)
21+
22+
You can use this to install `diesel_cli` with only PostgreSQL:
23+
24+
cargo install diesel_cli --no-default-features --features postgres
25+
26+
> If you encounter linker errors related to `-lpq`:
27+
>
28+
> note: ld: library not found for -lpq
29+
> clang: error: linker command failed with exit code 1 (use -v to see invocation)
30+
>
31+
> Install and link `libpq` using:
32+
>
33+
> brew install libpq
34+
> brew link --force libpq
35+
36+
## Setup Instructions
37+
38+
### 1. Clone the repository:
39+
40+
Checkout the code:
41+
42+
git clone git@github.com:edly-io/sparkth_backend.git
43+
cd sparkth_backend
44+
45+
### 2. Create a `.env` file
46+
47+
cp .env.example .env
48+
49+
Make sure to set all required values in your `.env` file.
50+
51+
### 3. Set Up the Database
52+
53+
Before running this step, make sure `diesel_cli` is installed. See the instructions above if you haven’t done that yet.
54+
55+
cd core
56+
diesel setup
57+
diesel migration run
58+
59+
## Running the API Server
60+
61+
From the project root, run the API crate:
62+
63+
cargo run -p api
64+
This will start the HTTP server on the address and port defined in your `.env` file

0 commit comments

Comments
 (0)