Skip to content

Commit 09ce0bb

Browse files
rajman01rajman01
committed
added readme.md
1 parent 28912c5 commit 09ce0bb

1 file changed

Lines changed: 195 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# AutoPlan-API
2+
3+
Backend API for the AutoPlan Web Application for the Geospatial Industry.
4+
5+
This repository contains a TypeScript + Express API that provides authentication, user/profile management, project and plan management, traverse and leveling computations, and integrations with MongoDB, Redis, AWS SES/Resend for email, and JWT-based auth.
6+
7+
## Table of contents
8+
9+
- About
10+
- Quick start
11+
- Project structure
12+
- Key concepts & architecture
13+
- Environment variables
14+
- Scripts
15+
- API reference (summary)
16+
- Development notes
17+
- Contributing
18+
- License
19+
20+
## About
21+
22+
The API is written in TypeScript and organized with a clean separation between adapters, domain (entities, errors, interfaces), use-cases, and infrastructure. The main entrypoint is `src/main/server.ts`, which wires the dependency container, connects to MongoDB and Redis, and starts the Express server.
23+
24+
Its primary features include:
25+
26+
- Authentication (OTP login, Google OAuth, JWT)
27+
- User profile management
28+
- Project CRUD
29+
- Plan creation and editing (coordinates, elevations, parcels, topo settings)
30+
- Traverse and leveling computations (forward/back computation, traverse computation, differential leveling)
31+
32+
## Quick start
33+
34+
Prerequisites:
35+
36+
- Node.js (v18+ recommended)
37+
- npm
38+
- A running MongoDB instance (or connection URI)
39+
- A Redis instance (for caching)
40+
41+
1. Install dependencies
42+
43+
```bash
44+
npm install
45+
```
46+
47+
2. Create an `.env` file at the project root. See the Environment variables section below for required keys.
48+
49+
3. Build the project
50+
51+
```bash
52+
npm run build
53+
```
54+
55+
4. Start the server (production build)
56+
57+
```bash
58+
npm start
59+
```
60+
61+
For local development you can build and run the output with nodemon (the repo uses a dist-first dev workflow):
62+
63+
```bash
64+
npm run build:watch # compile in watch mode
65+
npm run dev # run the compiled server with nodemon
66+
```
67+
68+
The API will be available at http://localhost:3000 (or the port defined in your `.env`). Health check: `GET /health`.
69+
70+
## Project structure
71+
72+
Top-level folders and a short description of their responsibilities:
73+
74+
- `src/main` — application wiring, server/bootstrap, routes, adapters and DI container.
75+
- `src/adapters` — controllers, cache adapters, and other framework adapters.
76+
- `src/domain` — core entities, types, errors and domain interfaces.
77+
- `src/use-cases` — application business logic (authentication, plan/project operations, computations).
78+
- `src/infrastructure` — concrete implementations for DB, redis, cryptography, email (SES/Resend), validator utilities, and configuration.
79+
- `src/repositories` — data access abstractions and implementations.
80+
- `src/utils` — utility functions such as distance calculations.
81+
82+
Important entry files:
83+
84+
- `src/main/server.ts` — program entrypoint.
85+
- `src/main/app.ts` — express app setup and route mounting.
86+
- `src/infrastructure/config/env.ts` — environment parsing and exported constants.
87+
88+
## Key concepts & architecture
89+
90+
The app uses dependency injection (a container defined in `src/main/config/container.ts`) to wire controllers, repositories, and adapters. The codebase follows a hexagonal/clean architecture style:
91+
92+
- Controllers (adapters) translate HTTP requests into use-case calls.
93+
- Use-cases contain application-specific business logic.
94+
- Repositories provide persistence abstractions used by use-cases.
95+
- Infrastructure provides concrete implementations (MongoDB, Redis, email, JWT, bcrypt).
96+
97+
Express routes are defined under `src/main/routes` and are mounted under the base path `/api/v1` in `App.setupRoutes()`.
98+
99+
## Environment variables
100+
101+
Create an `.env` file with the following keys (the app reads them from `src/infrastructure/config/env.ts`):
102+
103+
- PORT — server port (default 3000)
104+
- JWT_SECRET — RSA/PEM string or symmetric secret used for JWT signing
105+
- ENCRYPTION_KEY — key for additional symmetric encryption used in the app
106+
- MONGO_URI — mongo connection string
107+
- REDIS_URI — redis connection string
108+
- RESEND_API_KEY — API key for resend.email (optional)
109+
- AWS_SECRET_KEY — AWS secret access key (optional, used for SES)
110+
- AWS_ACCESS_KEY — AWS access key id (optional)
111+
- AWS_BUCKET — S3 bucket name (optional)
112+
- AWS_REGION — AWS region (optional)
113+
- AWS_SES_SENDER — Verified sender email for SES (optional)
114+
115+
Note: `JWT_SECRET` is parsed using `parsePemKey` helper (turns literal `\n` into newlines). If you use multi-line PEMs in an env file, escape newlines as `\n`.
116+
117+
## Scripts
118+
119+
- `npm run build` — cleans `dist`, copies html assets and runs `tsc` with `tsconfig-build.json` (produces `dist`).
120+
- `npm run build:watch` — builds in watch mode.
121+
- `npm run dev` — runs `nodemon` on the compiled `dist/main/server.js` (the repo uses a dist-first dev workflow).
122+
- `npm start` — runs the compiled server from `dist`.
123+
124+
## API reference (summary)
125+
126+
All API endpoints are mounted under `/api/v1`.
127+
128+
Auth
129+
130+
- POST /api/v1/auth/login/otp — Send login OTP
131+
- POST /api/v1/auth/login — Login with credentials or OTP
132+
- POST /api/v1/auth/login/google — Login with Google
133+
- GET /api/v1/auth/logout — Logout (protected)
134+
135+
User (protected)
136+
137+
- POST /api/v1/user/profile/set — Set or update profile
138+
- GET /api/v1/user/profile/fetch — Fetch user profile
139+
140+
Project (protected)
141+
142+
- POST /api/v1/project/create — Create project
143+
- GET /api/v1/project/list — List projects
144+
- GET /api/v1/project/fetch/:project_id — Fetch project by id
145+
- PUT /api/v1/project/edit/:project_id — Edit project
146+
- DELETE /api/v1/project/delete/:project_id — Delete project
147+
148+
Plan (protected)
149+
150+
- POST /api/v1/plan/create — Create plan
151+
- GET /api/v1/plan/list/:project_id — List plans for project
152+
- GET /api/v1/plan/fetch/:plan_id — Fetch plan
153+
- PUT /api/v1/plan/edit/:plan_id — Edit plan
154+
- PUT /api/v1/plan/coordinates/edit/:plan_id — Edit coordinates
155+
- PUT /api/v1/plan/elevations/edit/:plan_id — Edit elevations
156+
- PUT /api/v1/plan/parcels/edit/:plan_id — Edit parcels
157+
- PUT /api/v1/plan/topo/boundary/edit/:plan_id — Edit topo boundary
158+
- PUT /api/v1/plan/topo/setting/edit/:plan_id — Edit topo setting
159+
- PUT /api/v1/plan/route/longitudinal/params/edit/:plan_id — Edit longitudinal profile parameters
160+
- PUT /api/v1/plan/traverse-data/edit/:plan_id — Edit traverse computation data
161+
- PUT /api/v1/plan/forward-data/edit/:plan_id — Edit forward computation data
162+
- PUT /api/v1/plan/differential-leveling-data/edit/:plan_id — Edit differential leveling data
163+
- GET /api/v1/plan/generate/:plan_id — Generate plan (export/compute)
164+
165+
Traverse & Leveling (some endpoints may be unprotected by default in routes)
166+
167+
- POST /api/v1/traverse/back-computation
168+
- POST /api/v1/traverse/forward-computation
169+
- POST /api/v1/traverse/traverse-computation
170+
- POST /api/v1/leveling/differential
171+
172+
For request/response shapes, consult the controllers in `src/adapters/controllers` and the use-cases under `src/use-cases`.
173+
174+
## Development notes
175+
176+
- The project uses module-alias mappings for runtime; in production those point to `dist/*` (configured in `package.json` under `_moduleAliases`).
177+
- The TypeScript build target is configured in `tsconfig-build.json` — the compiled code is placed into `dist` and the app expects `dist/main/server.js` as the entry.
178+
- The DI container is defined at `src/main/config/container.ts` — register additional implementations there if you add services.
179+
180+
## Contributing
181+
182+
If you want to contribute, please:
183+
184+
1. Fork the repository
185+
2. Create a feature branch
186+
3. Make changes and add unit tests where appropriate
187+
4. Open a PR describing your changes
188+
189+
Automated tests are currently absent from this repository. It is strongly recommended to implement unit and integration tests for critical features such as authentication, computations, and data operations. Contributors are encouraged to include relevant tests with their changes to improve reliability and maintainability.
190+
191+
## License
192+
193+
This repository is licensed under ISC (see `package.json`).
194+
195+
---

0 commit comments

Comments
 (0)