# pujan1/tesla_power_planner architecture

> Architecture diagram of the GitHub repository pujan1/tesla_power_planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pujan1/tesla_power_planner
- Repository: https://github.com/pujan1/tesla_power_planner

## Overview

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: [`frontend/src/App.tsx`](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/App.tsx) (React app), [`backend/src/api/users/user.routes.ts`](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/api/users/user.routes.ts) (Users API), [`frontend/src/features/site-planner/components/SitePlanner.tsx`](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/SitePlanner.tsx) (Site planner), [`package.json`](https://github.com/pujan1/tesla_power_planner/blob/master/package.json) (Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend"]
  node_node_frontend_app["React app<br/>client app<br/>[App.tsx]"]
  node_node_main_layout["App shell<br/>layout shell<br/>[MainLayout.tsx]"]
  node_node_contexts(("App context<br/>state context<br/>[ThemeContext.tsx]"))
  node_node_api_hook["API hook<br/>client API<br/>[useApi.ts]"]
  node_node_auth_area["Auth area<br/>feature area<br/>[LoginForm.tsx]"]
  node_node_dashboard_area["Dashboard area<br/>feature area<br/>[DashboardView.tsx]"]
  node_node_site_planner["Site planner<br/>planner feature<br/>[SitePlanner.tsx]"]
  node_node_sp_context(("Planner state<br/>feature context"))
  node_node_sp_hook["Planner hook<br/>feature hook<br/>[useSitePlanner.ts]"]
  node_node_sp_helpers["Planner logic<br/>helper layer"]
  node_node_sp_canvas["2D/3D canvas<br/>rendering<br/>[SiteCanvas.tsx]"]
  node_node_sp_ui["Planner UI<br/>feature components<br/>[ViewToggle.tsx]"]
end

subgraph group_group_backend["Backend"]
  node_node_backend_server["Server entry<br/>api entry<br/>[server.ts]"]
  node_node_backend_loaders["Loaders<br/>runtime setup<br/>[index.ts]"]
  node_node_backend_config["Config<br/>[index.ts]"]
  node_node_users_api["Users API<br/>domain module<br/>[user.routes.ts]"]
  node_node_backend_utils["API utils<br/>cross-cutting<br/>[ApiError.ts]"]
  node_node_backend_auth["Auth middleware<br/>security middleware<br/>[authMiddleware.ts]"]
  node_node_mongo[("MongoDB<br/>database<br/>[mongoose.ts]")]
end

subgraph group_group_shared["Shared"]
  node_node_shared_contracts["Contracts<br/>shared types<br/>[index.ts]"]
end

subgraph group_group_quality["Quality"]
  node_node_backend_tests["Backend tests<br/>unit tests"]
  node_node_frontend_tests["Frontend tests<br/>component and hook tests"]
  node_node_e2e["Playwright e2e<br/>end-to-end tests"]
end

subgraph group_group_ops["Ops"]
  node_node_workspace["Workspace<br/>monorepo bootstrap<br/>[package.json]"]
  node_node_setup["Setup script<br/>bootstrap script<br/>[setup.js]"]
  node_node_render["Render deploy<br/>deployment<br/>[render.yaml]"]
end

node_node_workspace -->|"bootstraps"| node_node_setup
node_node_workspace -->|"builds shared"| node_node_shared_contracts
node_node_workspace -->|"starts backend"| node_node_backend_server
node_node_workspace -->|"starts frontend"| node_node_frontend_app
node_node_frontend_app -->|"uses shell"| node_node_main_layout
node_node_frontend_app -->|"provides state"| node_node_contexts
node_node_frontend_app -->|"calls api"| node_node_api_hook
node_node_frontend_app -->|"renders auth"| node_node_auth_area
node_node_frontend_app -->|"renders dashboard"| node_node_dashboard_area
node_node_frontend_app -->|"renders planner"| node_node_site_planner
node_node_site_planner -->|"shares state"| node_node_sp_context
node_node_site_planner -->|"orchestrates"| node_node_sp_hook
node_node_sp_hook -->|"computes"| node_node_sp_helpers
node_node_sp_hook -->|"drives render"| node_node_sp_canvas
node_node_sp_hook -->|"coordinates ui"| node_node_sp_ui
node_node_site_planner -->|"uses contracts"| node_node_shared_contracts
node_node_backend_server -->|"initializes"| node_node_backend_loaders
node_node_backend_server -->|"reads config"| node_node_backend_config
node_node_backend_loaders -->|"mounts domain"| node_node_users_api
node_node_backend_loaders -->|"connects db"| node_node_mongo
node_node_users_api -->|"uses helpers"| node_node_backend_utils
node_node_users_api -->|"protected by"| node_node_backend_auth
node_node_users_api -->|"shares types"| node_node_shared_contracts
node_node_users_api -->|"persists"| node_node_mongo
node_node_backend_tests -.->|"covers"| node_node_users_api
node_node_frontend_tests -.->|"covers"| node_node_site_planner
node_node_e2e -.->|"exercises"| node_node_frontend_app
node_node_render -->|"deploys"| node_node_backend_server
node_node_render -->|"serves app"| node_node_frontend_app

click node_node_workspace "https://github.com/pujan1/tesla_power_planner/blob/master/package.json"
click node_node_setup "https://github.com/pujan1/tesla_power_planner/blob/master/scripts/setup.js"
click node_node_frontend_app "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/App.tsx"
click node_node_main_layout "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/layouts/MainLayout.tsx"
click node_node_contexts "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/context/ThemeContext.tsx"
click node_node_api_hook "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/hooks/useApi.ts"
click node_node_auth_area "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/auth/components/LoginForm.tsx"
click node_node_dashboard_area "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/dashboard/components/DashboardView.tsx"
click node_node_site_planner "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/SitePlanner.tsx"
click node_node_sp_context "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/context/SitePlannerContext.tsx"
click node_node_sp_hook "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/hooks/useSitePlanner.ts"
click node_node_sp_helpers "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/helpers/site-planner.helpers.ts"
click node_node_sp_canvas "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/SiteCanvas.tsx"
click node_node_sp_ui "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/ViewToggle.tsx"
click node_node_shared_contracts "https://github.com/pujan1/tesla_power_planner/blob/master/shared/src/index.ts"
click node_node_backend_server "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/server.ts"
click node_node_backend_loaders "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/loaders/index.ts"
click node_node_backend_config "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/config/index.ts"
click node_node_users_api "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/api/users/user.routes.ts"
click node_node_backend_utils "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/utils/ApiError.ts"
click node_node_backend_auth "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/middlewares/authMiddleware.ts"
click node_node_mongo "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/loaders/mongoose.ts"
click node_node_backend_tests "https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/api/users/__tests__/user.service.test.ts"
click node_node_frontend_tests "https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/hooks/__tests__/useSitePlanner.test.tsx"
click node_node_e2e "https://github.com/pujan1/tesla_power_planner/blob/master/e2e/tests/site-planner-workflow.spec.ts"
click node_node_render "https://github.com/pujan1/tesla_power_planner/blob/master/render.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_frontend_app,node_node_main_layout,node_node_contexts,node_node_api_hook,node_node_auth_area,node_node_dashboard_area,node_node_site_planner,node_node_sp_context,node_node_sp_hook,node_node_sp_helpers,node_node_sp_canvas,node_node_sp_ui toneBlue
class node_node_backend_server,node_node_backend_loaders,node_node_backend_config,node_node_users_api,node_node_backend_utils,node_node_backend_auth,node_node_mongo toneAmber
class node_node_shared_contracts toneMint
class node_node_backend_tests,node_node_frontend_tests,node_node_e2e toneRose
class node_node_workspace,node_node_setup,node_node_render toneIndigo
```

## Components

### Frontend

React client application and feature subsystems

- [React app](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/App.tsx): client app · Main frontend application shell and entry points · `frontend/src/App.tsx`
- [App shell](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/layouts/MainLayout.tsx): layout shell · Global layout wrappers for main and dashboard areas · `frontend/src/layouts/MainLayout.tsx`
- [App context](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/context/ThemeContext.tsx): state context · Theme and language providers for cross-cutting UI state · `frontend/src/context/ThemeContext.tsx`
- [API hook](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/hooks/useApi.ts): client API · Central hook for backend communication and request handling · `frontend/src/hooks/useApi.ts`
- [Auth area](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/auth/components/LoginForm.tsx): feature area · Login and account creation UI · `frontend/src/features/auth/components/LoginForm.tsx`
- [Dashboard area](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/dashboard/components/DashboardView.tsx): feature area · Authenticated dashboard view and user controls · `frontend/src/features/dashboard/components/DashboardView.tsx`
- [Site planner](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/SitePlanner.tsx): planner feature · Client-heavy planning subsystem with its own state, helpers, and rendering pipeline · `frontend/src/features/site-planner/components/SitePlanner.tsx`
- [Planner state](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/context/SitePlannerContext.tsx): feature context · Planner context boundary for shared interactive state · `frontend/src/features/site-planner/context/SitePlannerContext.tsx`
- [Planner hook](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/hooks/useSitePlanner.ts): feature hook · Primary orchestration hook for planner behavior · `frontend/src/features/site-planner/hooks/useSitePlanner.ts`
- [Planner logic](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/helpers/site-planner.helpers.ts): helper layer · Packing, validation, scene composition, and planner rules · `frontend/src/features/site-planner/helpers/site-planner.helpers.ts`
- [2D/3D canvas](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/SiteCanvas.tsx): rendering · Visual output surfaces for planner interactions and scene rendering · `frontend/src/features/site-planner/components/SiteCanvas.tsx`
- [Planner UI](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/components/ViewToggle.tsx): feature components · 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](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/server.ts): api entry · Backend process entry point for the Express application · `backend/src/server.ts`
- [Loaders](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/loaders/index.ts): runtime setup · Express and Mongoose initialization chain · `backend/src/loaders/index.ts`
- [Config](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/config/index.ts): env config · Central environment and runtime configuration · `backend/src/config/index.ts`
- [Users API](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/api/users/user.routes.ts): domain module · User-facing backend domain organized by route, controller, service, repository, and model · `backend/src/api/users/user.routes.ts`
- [API utils](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/utils/ApiError.ts): cross-cutting · Error and async helper utilities plus error middleware · `backend/src/utils/ApiError.ts`
- [Auth middleware](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/middlewares/authMiddleware.ts): security middleware · Request protection boundary for guarded backend routes · `backend/src/middlewares/authMiddleware.ts`
- [MongoDB](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/loaders/mongoose.ts): database · Persistence boundary accessed through Mongoose models and repositories · `backend/src/loaders/mongoose.ts`

### Shared

Cross-app contracts and types

- [Contracts](https://github.com/pujan1/tesla_power_planner/blob/master/shared/src/index.ts): shared types · 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](https://github.com/pujan1/tesla_power_planner/blob/master/backend/src/api/users/__tests__/user.service.test.ts): unit tests · Backend unit coverage focused on user service behavior · `backend/src/api/users/__tests__/user.service.test.ts`
- [Frontend tests](https://github.com/pujan1/tesla_power_planner/blob/master/frontend/src/features/site-planner/hooks/__tests__/useSitePlanner.test.tsx): component and hook tests · React and planner test coverage for UI and planner logic · `frontend/src/features/site-planner/hooks/__tests__/useSitePlanner.test.tsx`
- [Playwright e2e](https://github.com/pujan1/tesla_power_planner/blob/master/e2e/tests/site-planner-workflow.spec.ts): end-to-end tests · Browser workflow coverage for the site planner experience · `e2e/tests/site-planner-workflow.spec.ts`

### Ops

Workspace bootstrap and deployment

- [Workspace](https://github.com/pujan1/tesla_power_planner/blob/master/package.json): monorepo bootstrap · Root package and setup script orchestrate install/build/start across packages · `package.json`
- [Setup script](https://github.com/pujan1/tesla_power_planner/blob/master/scripts/setup.js): bootstrap script · Repository setup and workspace startup coordination · `scripts/setup.js`
- [Render deploy](https://github.com/pujan1/tesla_power_planner/blob/master/render.yaml): deployment · Production deployment configuration for the repo · `render.yaml`

## Connections

- 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
