Architecture Intelligence Platform

Search architectural project knowledge, retrieve document evidence and match project experience to RFP requirements. A vanilla JavaScript 3D archive connects to a Spring Boot platform backed by PostgreSQL and OpenSearch.

Overview

The platform combines structured architectural data with searchable project documents. PostgreSQL owns the records, documents, embeddings and matching evidence. OpenSearch supplies a rebuildable retrieval index. Explicit hard constraints keep architectural compliance separate from text similarity.

Product Experience

• A closed, 136-card interactive archive with desktop scroll/hover and mobile drag/inertia.
• A backend project catalogue, editorial search and shareable project details.
• Lazy document metadata and passage excerpts.
• Authenticated Insights for owned RFPs, ranked project matches and requirement evidence.
• A local presentation fallback that keeps the archive usable when the API is unavailable.

The included projects, architectural attributes, documents and procurement briefs are synthetic demonstration content. The fifteen photographs are independently licensed illustrative assets; they do not depict the fictional project records.

Architecture

flowchart LR
    UI[HTML / CSS / JavaScript + GSAP] --> Adapter[Browser API adapters]
    Adapter --> API[Spring Boot API]
    API --> PG[(PostgreSQL)]
    API --> OS[(OpenSearch)]
    API --> Storage[Filesystem / S3]
    PG --> Outbox[Transactional outbox]
    Outbox --> SQS[SQS]
    SQS --> Worker[Platform worker]
    Worker --> PG
    Worker --> OS
    Worker --> Embeddings[Embedding provider]

Loading

One Maven artifact contains the domain modules and supports API and worker roles. The browser adapter boundary keeps backend DTOs and request handling out of the animation engine. See architecture, frontend design and the architectural decisions.

Backend Capabilities

• Project/domain persistence, lifecycle checks and field provenance.
• PDF/text ingestion, validation, normalization, chunking and filesystem/S3 storage.
• Embedding provider abstraction and versioned embedding persistence.
• Lexical, structured and hybrid retrieval with explicit ranking contributions.
• Alias-managed index generations, rebuilds and consistency reconciliation.
• Rule-based RFP requirement extraction, hard-constraint evaluation and evidence-based matching.
• Transactional outbox publishing, SQS delivery and processed-message deduplication.

Frontend

The frontend uses HTML, CSS, native ES modules and GSAP/ScrollTrigger, without a framework or bundler. Fifteen presentation slots expand deterministically to exactly 136 cards; repeated cards retain their canonical project identity. Search, details and Insights use a native dialog with keyboard focus handling, Escape dismissal and browser history. API requests are bounded, cancellable and independent of animation frames.

Technology

Java 21, Spring Boot 3.5, Maven, PostgreSQL 16, Flyway, OpenSearch 2.18, AWS SDK for SQS/S3, PDFBox, Micrometer/OpenTelemetry, Terraform, Docker Compose, HTML/CSS/JavaScript, GSAP and Playwright.

API

Surface	Principal routes	Access
Projects	GET /api/v1/projects, GET /api/v1/projects/{projectRef}	Public
Search	POST /api/v1/search, POST /api/v1/facets	Public
Documents	GET /api/v1/projects/{projectRef}/documents and document/chunk routes	Public project content
RFPs	/api/v1/rfps, /{rfpRef}, /{rfpRef}/matches	Authenticated owner; matching requires EDITOR/ADMIN
Authentication	POST /api/v1/auth/login	Existing accounts
Health	/actuator/health, /actuator/health/liveness, /actuator/health/readiness	Public, without diagnostic details

The OpenAPI contract describes request/response schemas and authorization. Account provisioning and operational maintenance are not public frontend features.

Testing

Unit tests cover domain transitions, parsing, embedding behavior, extraction and requirement evaluation. Integration tests use real PostgreSQL, OpenSearch and SQS-compatible services to exercise persistence, authorization, indexing and message delivery. Frontend boundary tests check normalization, fallback, request races and visual invariants; Playwright covers desktop, mobile, keyboard, Insights and failure handling.

mvn -f services/platform/pom.xml clean verify
npm ci
npm test
npm run test:browser

Full backend verification requires the disposable test database and local services. Browser tests require the running frontend/API, seeded synthetic corpus, installed Chrome and caller-supplied local demo credentials. Missing integration dependencies can produce explicit JUnit skips; those do not constitute a complete verification. See development, search evaluation and performance.

Verified suites contain 101 backend unit tests, 43 integration tests, 23 frontend boundary/preservation tests, 12 browser tests and 3 browser security checks, with no failures or skips. Parsing coverage includes sanitized errors for malformed PDFs. The Maven verification gate includes formatting, packaging and static analysis.

Local Development

1. Install JDK 21, Maven 3.9 and Node.js 20.11 or newer.
2. Supply local database and signing credentials through your environment. Start PostgreSQL, OpenSearch and ElasticMQ using the Docker configuration or portable Windows scripts.
3. Build the platform, then start it with the local profile. Demo seeding is an explicit opt-in and requires your own demo password.
4. Run npm start from the repository root. Open http://127.0.0.1:5179; the API defaults to http://127.0.0.1:8080.

The development guide provides exact commands, variables, tool layout and database safeguards. ARCHITECTURE_API_BASE_URL configures the local frontend server. Deployed static assets use the small public config.js file; no credentials belong in it.

Infrastructure

The repository includes Terraform definitions for ECS/Fargate, RDS PostgreSQL, OpenSearch, SQS, S3, private networking, CloudFront and observability. Dev/staging/prod roots compose the same modules. This is infrastructure-as-code, not a claim of a live AWS deployment. Provisioning, routing, certificates, credentials and alarm destinations require deployment-specific configuration.

Docker Compose defines loopback-bound local dependencies and API/worker services. Docker runtime/build verification is unavailable on the validation workstation; its source has been statically audited. See the deployment topology and runbook.

Security

JWT authentication protects private RFPs; ownership is checked in the service layer. CORS uses explicit allowed origins. Frontend tokens stay in memory, errors are normalized and the local static server exposes only browser assets. Production requires supplied credentials and excludes demo seeding. Project documents are public archive content and must not contain confidential information. See security.

Assets and Licensing

Photograph creators, source pages, CC0 records and transformations are documented in ASSETS.md. Third-party dependency terms remain applicable; see dependency notices. No repository-wide license selected. The asset licenses do not grant a license to the project source as a whole.

Limitations

• The included corpus demonstrates mechanisms, not facts about real buildings or procurement.
• Local embeddings are deterministic token-overlap vectors, not a learned semantic model. The HTTP provider supports an external embedding service; no particular model deployment is claimed.
• RFP extraction is rule-based. Matching scores are ranking signals, not confidence or professional compliance certification.
• Production routing, security boundaries, secrets, capacity and monitoring require deployment-specific preparation. Infrastructure has not been deployed here.
• Docker runtime/build and Safari/physical-device behavior remain unverified on this workstation. Browser coverage uses desktop Chrome and mobile emulation.