How mrbacony/analog-tools works
Project Type and Purpose
• This is an Nx monorepo (“AnalogTools”) that contains:
• A full-stack example app (apps/analog-example) built on AnalogJS (Angular SSR + Vite) with both REST (v1) and tRPC endpoints.
• Two reusable libraries under packages/:
– @analog-tools/auth: OAuth flows, route guards, session middleware
– @analog-tools/session: Pluggable session store layer (Redis, Unstorage)
• A Docker folder provisioning a Keycloak realm for OAuth.
• GitHub CI/CD workflows for testing and releases.
File Structure and Architectural Insights
• Top-level Nx workspace orchestrates builds, linting, tests, and deployments.
• apps/analog-example/ splits into:
• Frontend: Angular components, pages, Tailwind/CSS, Vite dev/server entry (main.ts)
• Backend: Node SSR entry (main.server.ts), Express-style middleware + routes under src/server, tRPC routers.
• packages/auth and packages/session are built via Rollup/Vite, then imported by the example app and potentially by other AnalogJS projects.
• Docker Compose runs Keycloak as the external identity provider; the session store package expects configurable backends (Redis, etc.).
Key Components & Relationships
A. Monorepo (Nx) Orchestration
– Manages tasks: nx serve analog-example, nx build
– Defines project boundaries, dependencies, and versioning for apps/ and packages/.
B. Example App
– Client (Browser)
• Angular + AnalogJS renders pages, consumes APIs via tRPC client or REST fetches.
• Auth redirects to Keycloak for login, receives callback, obtains tokens.
– Server (Node)
• Serves SSR pages; exposes API layers:
· tRPC endpoint (/api/trpc/[trpc])
· REST endpoint (/api/v1/hello, etc.)
• Applies middleware: session loader (useAnalogAuthMiddleware), route protection.
• Delegates to auth/session libraries for OAuth logic and session persistence.
C. Auth & Session Libraries
– Imported by the app’s server code.
– Perform OAuth token exchange with Keycloak, create/manage session objects, store in Redis or Unstorage.
D. External Services
– Keycloak (Docker): OAuth authorization server.
– Redis (not shown in Docker Compose but supported by session package).
E. CI/CD
– GitHub Actions pipelines: unit tests, lint, release publishing.
Architectural Patterns & Design Principles
• Monorepo & shared-library pattern (Nx)
• Full-stack meta-framework (AnalogJS) combining SSR + client hydration
• API layering: tRPC for type-safe RPC, REST for legacy or simple endpoints
• Middleware pipeline for auth/session
• Pluggable persistence via abstract store interfaces in session library
Final Recommendations
• Be exhaustive in labeling every API surface and middleware stage without cluttering—use callouts or legends where needed.