How pujan1/tesla_power_planner works
1. Top-level shape: a TypeScript monorepo
- The repository is split into frontend, backend, shared, and e2e.
- Source lives in src folders; compiled output is checked into dist for backend and shared.
- The root package.json plus scripts/setup.js suggest a workspace-style bootstrap that installs, builds shared types, and starts the apps together.
2. Shared contract layer
- shared/src/index.ts is the common type/package boundary.
- This package is used to keep frontend and backend aligned on data models and DTO shapes, reducing contract drift across the stack.
- In an architecture diagram, this is the central “types/contracts” block connecting both applications.
3. Backend runtime boundary
- The backend is an Express API built in TypeScript under backend/src.
- Startup is organized through loaders: loaders/express.ts and loaders/mongoose.ts, with server.ts as the entry point.
- config/index.ts centralizes environment/config values, and .env.example indicates runtime configuration via environment variables.
4. Backend domain structure
- The only explicit domain in the tree is api/users.
- It follows a clear layered pattern: routes -> controller -> service -> repository -> model.
- This is the main request flow for backend calls, with controllers handling HTTP concerns, services containing business logic, repositories handling persistence, and Mongoose models mapping to MongoDB documents.
5. Backend persistence and cross-cutting concerns
- Persistence is via MongoDB + Mongoose.
- Cross-cutting utilities include ApiError, catchAsync, and middlewares/errorHandler.ts.
- There is also middlewares/authMiddleware.ts, indicating request protection/security checks are part of the backend boundary, even though the auth domain itself is not fully visible in the tree.
6. Frontend application shell
- The frontend is a React app with a feature-oriented folder structure.
- Cross-cutting app state is handled through context/ThemeContext.tsx and context/LanguageContext.tsx.
- Shared UI configuration and API endpoint setup live in src/config/api.config.ts, while useApi.ts is the central hook for backend communication.
7. Frontend feature boundaries
- The UI is organized by product areas: auth, dashboard, landing, and site-planner.
- Layout components (MainLayout, DashboardLayout) wrap the feature pages and separate global shell concerns from feature logic.
- The design system is componentized under components/ui and styled with CSS Modules for local style isolation.
8. Site planner is the core client-side subsystem
- The features/site-planner area is the most substantial subsystem in the repo.
- It includes:
- a dedicated context (SitePlannerContext)
- a custom hook (useSitePlanner)
- helper libraries for packing, validation, scene composition, and domain logic
- UI components for 2D/3D rendering, view toggling, sales modal, submission success, and markers
- This strongly suggests a client-heavy planning engine where most layout state and optimization occur locally in the browser.
9. Site planner data flow
- User interactions enter through the planner components.
- State and behavior are funneled into useSitePlanner, which uses the helper layer to compute layout, validation, and packing outcomes.
- The output is rendered into either a 2D canvas or a 3D scene (SiteCanvas, SiteCanvas3D), with supporting visual elements like BatteryMesh and ParkingMarker.
- If there is server interaction for authentication or persistence, it is abstracted away from the planner into hooks and API config rather than being embedded in the feature components.
10. Authentication and user-facing app areas
- The auth feature contains login and account creation forms.
- The dashboard feature includes a user settings dropdown and a dashboard view, implying a post-login application area.
- These areas likely rely on backend user APIs and the auth middleware for protected routes, even though the exact auth endpoints are not shown in the tree.
11. Testing strategy is layered
- Backend unit tests live under backend/src/api/users/__tests__.
- Frontend component and hook tests exist under frontend/src/features/site-planner/.../__tests__ plus app-level tests.
- End-to-end coverage is handled separately in e2e/tests using Playwright, which exercises the full browser flow across frontend and backend.
12. Build, deployment, and operational boundaries
- The presence of render.yaml indicates deployment on Render.
- The repo is built for a production pipeline that compiles TypeScript, ships frontend assets, and runs the Node/Express backend.
- The backend/dist and shared/dist folders show the compiled deployment artifacts, while the frontend remains source-driven for its own build pipeline.
13. What to show in an architecture diagram
- Draw three main executable blocks: frontend React app, backend Express/Mongo API, and shared types package.
- Show the site planner as the dominant frontend subsystem, with its own context/hook/helper pipeline.
- Show the backend as a conventional layered API with MongoDB at the persistence boundary.
- Add a separate testing lane for Jest and Playwright, and a deployment lane through Render.
Main entry points: App.tsx React app · user.routes.ts Users API · SitePlanner.tsx Site planner · package.json Workspace
Components 26
Frontend
React client application and feature subsystems
- React app · Main frontend application shell and entry points
frontend/src/App.tsx - App shell · Global layout wrappers for main and dashboard areas
frontend/src/layouts/MainLayout.tsx - App context · Theme and language providers for cross-cutting UI state
frontend/src/context/ThemeContext.tsx - API hook · Central hook for backend communication and request handling
frontend/src/hooks/useApi.ts - Auth area · Login and account creation UI
frontend/src/features/auth/components/LoginForm.tsx - Dashboard area · Authenticated dashboard view and user controls
frontend/src/features/dashboard/components/DashboardView.tsx - Site planner · Client-heavy planning subsystem with its own state, helpers, and rendering pipeline
frontend/src/features/site-planner/components/SitePlanner.tsx - Planner state · Planner context boundary for shared interactive state
frontend/src/features/site-planner/context/SitePlannerContext.tsx - Planner hook · Primary orchestration hook for planner behavior
frontend/src/features/site-planner/hooks/useSitePlanner.ts - Planner logic · Packing, validation, scene composition, and planner rules
frontend/src/features/site-planner/helpers/site-planner.helpers.ts - 2D/3D canvas · Visual output surfaces for planner interactions and scene rendering
frontend/src/features/site-planner/components/SiteCanvas.tsx - Planner UI · Markers, toggles, modals, and success feedback around the planner flow
frontend/src/features/site-planner/components/ViewToggle.tsx
Backend
Express API, loaders, persistence, and domain logic
- Server entry · Backend process entry point for the Express application
backend/src/server.ts - Loaders · Express and Mongoose initialization chain
backend/src/loaders/index.ts - Config · Central environment and runtime configuration
backend/src/config/index.ts - Users API · User-facing backend domain organized by route, controller, service, repository, and model
backend/src/api/users/user.routes.ts - API utils · Error and async helper utilities plus error middleware
backend/src/utils/ApiError.ts - Auth middleware · Request protection boundary for guarded backend routes
backend/src/middlewares/authMiddleware.ts - MongoDB · Persistence boundary accessed through Mongoose models and repositories
backend/src/loaders/mongoose.ts
Shared
Cross-app contracts and types
- Contracts · Common data models and DTO boundary shared by frontend and backend
shared/src/index.ts
Quality
End-to-end and unit testing surfaces
- Backend tests · Backend unit coverage focused on user service behavior
backend/src/api/users/__tests__/user.service.test.ts - Frontend tests · React and planner test coverage for UI and planner logic
frontend/src/features/site-planner/hooks/__tests__/useSitePlanner.test.tsx - Playwright e2e · Browser workflow coverage for the site planner experience
e2e/tests/site-planner-workflow.spec.ts
Ops
Workspace bootstrap and deployment
- Workspace · Root package and setup script orchestrate install/build/start across packages
package.json - Setup script · Repository setup and workspace startup coordination
scripts/setup.js - Render deploy · Production deployment configuration for the repo
render.yaml
Connections 29
- Workspace → Setup script: bootstraps · Workspace setup script is part of the top-level initialization flow
- Workspace → Contracts: builds shared · Shared package is built as a workspace dependency
- Workspace → Server entry: starts backend · Root scripts coordinate backend startup
- Workspace → React app: starts frontend · Root scripts coordinate frontend startup
- React app → App shell: uses shell · Main and dashboard layouts wrap the app experience
- React app → App context: provides state · App-wide providers expose theme and language state
- React app → API hook: calls api · Frontend communication is routed through the central API hook
- React app → Auth area: renders auth · Login and account creation are frontend feature areas
- React app → Dashboard area: renders dashboard · Dashboard UI is a distinct authenticated area
- React app → Site planner: renders planner · Site planner is the dominant client-side subsystem
- Site planner → Planner state: shares state · Planner feature state is centralized in context
- Site planner → Planner hook: orchestrates · Planner hook coordinates user interaction and derived state
- Planner hook → Planner logic: computes · Planner behavior delegates to helper logic for packing and validation
- Planner hook → 2D/3D canvas: drives render · Derived planner state feeds 2D and 3D rendering surfaces
- Planner hook → Planner UI: coordinates ui · Planner hook also feeds toggles, modals, and success states
- Site planner → Contracts: uses contracts · Planner data models align with the shared contract package
- Server entry → Loaders: initializes · Server entry delegates startup wiring to loaders
- Server entry → Config: reads config · Server boot depends on centralized environment configuration
- Loaders → Users API: mounts domain · Express setup mounts the users domain routes
- Loaders → MongoDB: connects db · Mongoose loader establishes database connectivity
- Users API → API utils: uses helpers · User flow uses async/error helpers and error handling
- Users API → Auth middleware: protected by · Routes can be guarded by auth middleware
- Users API → Contracts: shares types · Backend domain aligns responses and DTOs with shared contracts
- Users API → MongoDB: persists · Repository/model layer stores user data in MongoDB
- Backend tests → Users API: covers · Backend unit tests focus on the users service layer
- Frontend tests → Site planner: covers · Frontend tests exercise planner hooks and components
- Playwright e2e → React app: exercises · Playwright runs the browser flow through the full stack UI
- Render deploy → Server entry: deploys · Render configuration targets the backend runtime
- Render deploy → React app: serves app · Deployment includes the frontend build and static delivery