Skip to content

Commit ba96659

Browse files
tobenottobenot
committed
feat: backend docs
1 parent 9441688 commit ba96659

File tree

2 files changed

+122
-0
lines changed

2 files changed

+122
-0
lines changed

‎docs/BACKEND_ARCHITECTURE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Backend Architecture Design
2+
3+
## 1. Introduction & Design Philosophy
4+
5+
### Purpose
6+
This document outlines the architectural philosophy and recommended technology stack for building modern, scalable, and type-safe backends that complement the Carrot Web Game Template. The primary goal is to create a blueprint that prioritizes developer experience and robust performance.
7+
8+
### Core Principles
9+
- **End-to-End Type Safety**: Eliminate a whole class of runtime errors by ensuring that types flow seamlessly from the database to the backend and all the way to the frontend React components. What you query from the database is what you get on the client, guaranteed.
10+
- **High Performance**: Utilize a low-overhead, high-throughput web framework to handle requests efficiently, ensuring the backend is never a bottleneck.
11+
- **Developer Experience**: Minimize boilerplate and manual type-wrangling. The development process should feel fast, intuitive, and enjoyable, with excellent autocompletion and clear error messages.
12+
- **Modularity & Scalability**: The architecture should be organized in a way that is easy to understand, maintain, and extend as the project grows.
13+
14+
## 2. Recommended Technology Stack
15+
16+
| Layer | Technology | Why? |
17+
|--------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
18+
| **Framework** | [**Fastify**](https://www.fastify.io/) | Blazing fast performance with minimal overhead. Its plugin-based architecture is powerful and it has first-class TypeScript support. |
19+
| **API Layer** | [**tRPC**](https://trpc.io/) | The cornerstone of our type-safe approach. It requires **no code generation** and allows you to write API endpoints that feel like calling local functions from the frontend. |
20+
| **Database ORM** | [**Prisma**](https://www.prisma.io/) | A next-generation ORM that provides a fully type-safe database client based on your schema. It makes database queries intuitive and safe. |
21+
| **Database** | [**PostgreSQL**](https://www.postgresql.org/) / [**SQLite**](https://www.sqlite.org/index.html) | PostgreSQL for production robustness; SQLite for zero-config, file-based local development and simple prototypes. Prisma supports both seamlessly. |
22+
23+
## 3. Data Flow Diagram
24+
25+
This diagram illustrates how data and types flow through the entire stack, creating a single, coherent system.
26+
27+
```mermaid
28+
graph TD
29+
subgraph "💻 Frontend (Your React App)"
30+
A[React Component] --> B{tRPC Client};
31+
end
32+
33+
subgraph "🚀 Backend (Fastify Server)"
34+
B --"HTTP Request"--> C[Fastify Adapter];
35+
C --> D[tRPC Router];
36+
D --"Calls procedure"--> E[Service/Logic];
37+
end
38+
39+
subgraph "💾 Database"
40+
E --"Database Query"--> F[Prisma Client];
41+
F --"SQL"--> G[(PostgreSQL/SQLite)];
42+
G --"Data"--> F;
43+
F --"Typed Results"--> E;
44+
end
45+
46+
E --"Typed Response"--> D;
47+
D --"JSON Response"--> C;
48+
C --"Types auto-inferred"--> B;
49+
B --"Fully-typed data & hooks"--> A;
50+
51+
linkStyle 1 stroke:#2980b9,stroke-width:2px;
52+
linkStyle 2 stroke:#2980b9,stroke-width:2px;
53+
linkStyle 3 stroke:#27ae60,stroke-width:2px;
54+
linkStyle 8 stroke:#27ae60,stroke-width:2px;
55+
linkStyle 9 stroke:#2980b9,stroke-width:2px;
56+
linkStyle 10 stroke:#2980b9,stroke-width:2px;
57+
58+
style A fill:#ecf0f1,stroke:#34495e;
59+
style B fill:#3498db,stroke:#2980b9,color:#fff;
60+
style C fill:#9b59b6,stroke:#8e44ad,color:#fff;
61+
style D fill:#e67e22,stroke:#d35400,color:#fff;
62+
style E fill:#ecf0f1,stroke:#34495e;
63+
style F fill:#1abc9c,stroke:#16a085,color:#fff;
64+
style G fill:#f1c40f,stroke:#f39c12;
65+
```

‎docs/PROJECT_DESIGN.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Backend Project Design: Basic-Web-Game-Backend
2+
3+
## 1. Project Vision & Purpose
4+
5+
The `Basic-Web-Game-Backend` project aims to be a **reusable, "batteries-included" backend template** designed to work seamlessly with the `Basic-Web-Game` frontend template.
6+
7+
Its purpose is to provide a solid, type-safe foundation for common game backend features, allowing developers to get a functional and secure backend running with minimal setup. This project will implement the principles and technologies outlined in the `BACKEND_ARCHITECTURE.md` document.
8+
9+
## 2. Initial Features (MVP - Minimum Viable Product)
10+
11+
The initial version of this template will focus on a core set of features essential to many web-based games.
12+
13+
1. **User Authentication**
14+
- **Mechanism**: Simple email and password-based authentication using JWTs (JSON Web Tokens).
15+
- **Endpoints**: `register`, `login`, and a protected `me` endpoint to fetch the current user's data.
16+
- **Future-Proofing**: The system will be designed to easily accommodate OAuth providers (like Discord or Google) in the future.
17+
18+
2. **Player Data Persistence**
19+
- **Mechanism**: A generic `UserProfile` model linked to the `User` model.
20+
- **Flexibility**: The `UserProfile` will include a `gameData` field of type `JSONB`. This allows different games to store arbitrary, game-specific player progress (e.g., stats, inventory, level) without requiring database schema changes, making the template highly reusable.
21+
22+
3. **Basic Leaderboard Service**
23+
- **Mechanism**: A simple `Leaderboard` model to store scores.
24+
- **Endpoints**: `submitScore` and `getTopScores` (e.g., top 100).
25+
26+
## 3. Proposed Project Structure
27+
28+
The project will follow a standard, modular structure for scalability and clarity.
29+
30+
```
31+
/
32+
├── prisma/
33+
│ ├── schema.prisma # Prisma schema for defining database models
34+
│ └── migrations/ # Database migration files
35+
├── src/
36+
│ ├── modules/ # Feature modules (e.g., auth, user, leaderboard)
37+
│ │ ├── auth/
38+
│ │ │ ├── auth.router.ts
39+
│ │ │ └── auth.service.ts
40+
│ │ └── ...
41+
│ ├── router.ts # Main tRPC router that merges all module routers
42+
│ ├── server.ts # Fastify server setup and startup
43+
│ ├── context.ts # tRPC context creation (e.g., attaching user to requests)
44+
│ └── utils/ # Utility functions (e.g., password hashing)
45+
├── .env.example # Example environment variables
46+
├── package.json
47+
└── tsconfig.json
48+
```
49+
50+
## 4. Deployment Strategy
51+
52+
- **Containerization**: A `Dockerfile` and `docker-compose.yml` will be provided for easy local development and production deployment.
53+
- **Hosting**: The containerized app is designed to be deployed on any modern cloud hosting platform, such as [Railway](https://railway.app/), [Fly.io](https://fly.io/), or any VPS.
54+
55+
## 5. Next Steps
56+
57+
The immediate development priority is to implement the **User Authentication** feature, as it is the foundation for all other user-specific functionalities.

0 commit comments

Comments
 (0)